What causes "invalid project id" in golang-migrate/migrate?

Append the project path to the URL: gitlab://user:token@host/group/project

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.

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)

Solutions

Append the project path to the URL: gitlab://user:token@host/group/project
Check that any variable interpolated into the connection string is non-empty at runtime
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")

Defensive patterns

Strategy: validation

Validate before calling

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")
}

Try / catch

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

Prevention

Keep the connection string in one constant/config value and review it
Validate the URL shape in unit tests for config loading
Avoid building the URL by naive string concatenation of possibly-empty parts

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

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