diff --git a/git/errors.go b/git/errors.go
index 39d63d9df..d22df4e83 100644
--- a/git/errors.go
+++ b/git/errors.go
@@ -2,6 +2,7 @@ package git
 
 import (
 	"errors"
+	"strings"
 
 	fluxerr "github.com/weaveworks/flux/errors"
 )
@@ -24,7 +25,7 @@ func CloningError(url string, actual error) error {
 	return &fluxerr.Error{
 		Type: fluxerr.User,
 		Err:  actual,
-		Help: `Problem cloning your git repository
+		Help: `Could not clone the upstream git repository
 
 There was a problem cloning your git repository,
 
@@ -44,6 +45,47 @@ cross-check with the fingerprint given by
 	}
 }
 
+func ErrUpstreamNotWritable(url string, actual error) error {
+	help := `Could not write to upstream repository
+
+To keep track of synchronisation, the flux daemon must be able to
+write to the upstream git repository.
+`
+	if strings.HasPrefix(url, "http://") ||
+		strings.HasPrefix(url, "https://") {
+		help = help + `
+Usually, git URLs starting with "http://" or "https://" will not work
+well with flux, because they require the user to supply credentials
+interactively. If possible, use an SSH URL (starting with "ssh://", or
+of the form "user@host:path/to/repo").
+`
+	} else {
+		help = help + `
+This failure may be due to the SSH (deploy) key used by the daemon not
+having write permission. You can see the key used, with
+
+    fluxctl identity
+
+In GitHub, please check via the repository settings that the deploy
+key is "Read/write". You can cross-check the fingerprint with that
+given by
+
+    fluxctl identity --fingerprint
+
+If the key is present but read-only, you will need to delete it and
+create a new deploy key. To create a new one, use
+
+    fluxctl identity --regenerate
+`
+	}
+
+	return &fluxerr.Error{
+		Type: fluxerr.User,
+		Err:  actual,
+		Help: help,
+	}
+}
+
 func PushError(url string, actual error) error {
 	return &fluxerr.Error{
 		Type: fluxerr.User,
@@ -57,7 +99,8 @@ If this has worked before, it most likely means a fast-forward push
 was not possible. It is safe to try again.
 
 If it has not worked before, this probably means that the repository
-exists but the deploy key provided doesn't have write permission.
+exists but the SSH (deploy) key provided doesn't have write
+permission.
 
 In GitHub, please check via the repository settings that the deploy
 key is "Read/write". You can cross-check the fingerprint with that
diff --git a/git/repo.go b/git/repo.go
index 7c43b89cf..60b579016 100644
--- a/git/repo.go
+++ b/git/repo.go
@@ -148,7 +148,10 @@ func (c *Checkout) ManifestDir() string {
 func (c *Checkout) CheckOriginWritable(ctx context.Context) error {
 	c.Lock()
 	defer c.Unlock()
-	return checkPush(ctx, c.repo.KeyRing, c.Dir, c.repo.URL)
+	if err := checkPush(ctx, c.repo.KeyRing, c.Dir, c.repo.URL); err != nil {
+		return ErrUpstreamNotWritable(c.repo.URL, err)
+	}
+	return nil
 }
 
 // CommitAndPush commits changes made in this checkout, along with any