golang-migrate/migrate · error

invalid project id

Error message

invalid project id

What it means

ErrInvalidProjectID is returned by gitlab.Open when the URL path does not contain a project id. Open strips the URL path and splits on '/'; if the resulting segments list is empty (no project path in the URL), it cannot determine which repository holds the migrations and returns this sentinel error.

Solutions

1. Append the project path to the URL: gitlab://user:token@host/group/project
2. Check that any variable interpolated into the connection string is non-empty at runtime
3. Trim stray trailing slashes and confirm the path segment after the host is present

Example fix

// before
db.Open("gitlab://oauth2:token@gitlab.example.com/")
// after
db.Open("gitlab://oauth2:token@gitlab.example.com/mygroup/myproject")

u, err := url.Parse(gitlabURL)
if err != nil {
    return err
}
if strings.Trim(u.Path, "/") == "" {
    return fmt.Errorf("gitlab URL must include group/project path")
}

d, err := gitlabDriver.Open(gitlabURL)
if errors.Is(err, gitlab.ErrInvalidProjectID) {
    log.Fatalf("missing project path in %s", gitlabURL)
}

When it happens

Trigger: Opening a gitlab:// driver whose URL path is empty or only slashes, e.g. gitlab://user:token@host/ — strings.Split of the trimmed path yields fewer than 1 element.

Common situations: Connection string copy/paste errors where the group/project suffix was dropped; building the URL programmatically with an unset project variable; trailing-slash-only URLs.

Understand the failure class

Background: "missing required config value" errors: why libraries refuse to start when a configuration key is empty, unset, or blank — this error's family across 48 libraries.

Related errors

• invalid host
• invalid repo
• no username:password provided
• no username:token provided
• unable to parse file

AI-assisted analysis of golang-migrate/migrate@01a9643f14 (2026-09-02). Data as JSON: /api/errors/a2a9f4e7078afc21. Report an issue: GitHub.

Appendix: source

Thrown at source/gitlab/gitlab.go:27

	"os"
	"strconv"
	"strings"

	"github.com/golang-migrate/migrate/v4/source"
	"github.com/xanzy/go-gitlab"
)

func init() {
	source.Register("gitlab", &Gitlab{})
}

const DefaultMaxItemsPerPage = 100

var (
	ErrNoUserInfo       = fmt.Errorf("no username:token provided")
	ErrNoAccessToken    = fmt.Errorf("no access token")
	ErrInvalidHost      = fmt.Errorf("invalid host")
	ErrInvalidProjectID = fmt.Errorf("invalid project id")
	ErrInvalidResponse  = fmt.Errorf("invalid response")
)

type Gitlab struct {
	client *gitlab.Client
	url    string

	projectID   string
	path        string
	listOptions *gitlab.ListTreeOptions
	getOptions  *gitlab.GetFileOptions
	migrations  *source.Migrations
}

type Config struct {
}

func (g *Gitlab) Open(url string) (source.Driver, error) {

View on GitHub (pinned to 01a9643f14)