FAQ

Module Path

Why must go.mod use the vanity URL instead of github.com/...?

When you set up a vanity URL like gomod.io/mylib, the Go toolchain uses the import path (the vanity URL) to locate the module. The module directive in go.mod must match exactly:

// go.mod — correct
module gomod.io/mylib

// go.mod — WRONG
module github.com/yourorg/mylib

If they don’t match, go get and go build will fail with an error like:

go: gomod.io/mylib@v0.1.0: parsing go.mod:
    module declares its path as: github.com/yourorg/mylib
    but was required as: gomod.io/mylib

How do I migrate an existing module to use a vanity URL?

1. Add a vanity URL route: gvu add gomod.io/mylib https://github.com/yourorg/mylib.git
2. Update go.mod: change module github.com/yourorg/mylib to module gomod.io/mylib
3. Update all internal imports within the module to use the new vanity path
4. Tag a new release: git tag v0.2.0 && git push --tags
5. Update any downstream consumers to use the new import path

Can I keep both github.com/... and the vanity URL working?

No. Go modules require the module directive in go.mod to be a single, canonical path. You cannot have two different module paths for the same code. Choose one and stick with it.

Do I need a separate route for major versions like /v2 or /v3?

No. Routes automatically support Go module major version suffixes (/v2, /v3, etc.). You only need to add the base route:

gvu add gomod.io/mylib https://github.com/yourorg/mylib.git

This single route serves gomod.io/mylib, gomod.io/mylib/v2, gomod.io/mylib/v3, and so on. The server detects the version suffix, strips it for route lookup, and includes it in the go-import meta tag prefix — fully compliant with the Go module specification.

Getting Started

Do I need an account to use gomod.io routes?

No. An anonymous account is created automatically when you run your first gvu add command. No email or signup is required. However, anonymous accounts are limited to 5 routes on the gomod.io domain.

How do I upgrade from Anonymous to Verified?

Run gvu auth bind your@email.com and enter the verification code sent to your email. This upgrades your account to Verified with up to 10 routes and access to custom domains.

What is GOPRIVATE and why do I need it?

GOPRIVATE tells the Go toolchain to fetch certain module paths directly from their source (via Git) rather than from the public Go proxy (proxy.golang.org). Without it, the proxy won’t be able to resolve your private vanity URLs.

export GOPRIVATE=gomod.io
# Add custom domains:
export GOPRIVATE=gomod.io,go.yourcompany.com

Quotas & Plans

How do I subscribe to Pro?

Run gvu subscribe and follow the interactive payment flow. After payment, an admin will verify your transaction (usually within 24 hours) and upgrade your account.

Which payment methods are supported?

You can choose monthly or yearly billing. See Pricing for details.

What happens to my routes if my Pro subscription expires?

If your Pro subscription expires, your account is downgraded to Verified (10 routes). Excess routes will be frozen. They are not deleted immediately — renew your subscription to reactivate them.

• Run gvu auth whoami to check your expiry date and remaining days
• A warning appears when 7 days or fewer remain
• After renewal, all frozen routes are automatically reactivated

Note: Frozen routes are retained for 90 days. If you do not renew within 90 days, frozen routes will be permanently deleted.

Custom Domains

How do I set up a custom domain?

1. Upgrade to Verified: gvu auth bind your@email.com
2. Create a CNAME DNS record: go.yourcompany.com → gomodvanityurls.com
3. Wait for DNS propagation (usually seconds to a few minutes)
4. Add a route: gvu add go.yourcompany.com/mylib https://github.com/yourorg/mylib.git
5. TLS certificates are provisioned automatically via Caddy On-Demand TLS

See Custom Domains for full details.

Does my custom domain need HTTPS?

No — TLS certificates are managed automatically. Once your CNAME is in place, HTTPS is provisioned on first request.

Why does gvu add require DNS to be configured first?

To prevent domain hijacking, the server verifies your domain’s CNAME record before creating the route. Configure the CNAME record first, wait for DNS propagation, then run gvu add. If DNS is not yet configured, you will receive a DNS_NOT_CONFIGURED error.

Can other users add routes under my custom domain?

• Pro users: No. When you add the first route under a custom domain, the domain is automatically bound to your account. Other users receive a DOMAIN_ALREADY_BOUND error.
• Verified users: Yes — Verified accounts can use custom domains but do not have exclusive domain binding. Upgrade to Pro to lock your domain.

What if someone bound my domain before me?

Contact support with proof of domain ownership (e.g., a DNS TXT record or domain registrar screenshot). We can transfer the binding after verification.

Does deleting all routes release the domain binding?

No. Domain bindings persist even after all routes under the domain are removed. This prevents accidental loss of your domain claim. Contact support to release a binding.

Wildcard Routing

What is wildcard routing?

Wildcard routing lets you cover all repos under a custom domain prefix with a single rule, instead of adding routes one by one. It requires a Pro account and a custom domain. See Wildcard Routing for details.

Can I use wildcard routes on gomod.io?

No. Wildcard routes are only available on custom domains. gomod.io routes use exact matching only.

Do wildcard routes count against my quota?

Yes. Each wildcard route counts as 1 route against your Pro quota (50 total), same as exact routes.

What happens if both a wildcard and exact route match?

Exact routes always take priority. Wildcard routes only apply when no exact match exists. See Priority rules.

Can I combine repo wildcard and subdir wildcard?

No. Repo wildcard (W1) and subdir wildcard (W2) are mutually exclusive per route. A single route can use one or the other, not both.

What if a repo matched by a wildcard doesn’t exist?

go get will fail with a “repository not found” error, same as with exact routes. The wildcard resolves the URL but the Git host must have the repo.

Do wildcard routes work after Pro expiry?

No special treatment — wildcard routes are frozen and deleted along with regular routes when your Pro subscription expires. See Pro expiry and renewal.

Troubleshooting

go get fails with “module declares its path as…”

This means your go.mod module path doesn’t match the vanity URL. Update go.mod to use the vanity URL. See Why must go.mod use the vanity URL?.

go get fails with “no Go modules found”

Check that GOPRIVATE includes your vanity domain:

go env GOPRIVATE

If it’s empty or missing your domain, set it:

go env -w GOPRIVATE=gomod.io

My route shows as “Frozen” in gvu list

A frozen route means your Pro subscription has expired and your account was downgraded to Verified (10 routes). Routes beyond the first 10 are frozen. Renew your subscription with gvu subscribe — all frozen routes are automatically reactivated once your Pro is active again. You can also remove excess routes with gvu remove. You have 90 days to renew before frozen routes are permanently removed.

The server returned RATE_LIMITED when I ran gvu add

Anonymous users are rate-limited to prevent abuse. Wait a few minutes and try again, or bind an email (gvu auth bind) to get higher limits.

Windows

Windows shows “Windows protected your PC” when running gvu.exe

This is Microsoft SmartScreen — it flags newly-published executables that haven’t accumulated enough download reputation yet. To bypass:

1. Click More info
2. Click Run anyway

Better alternatives that avoid SmartScreen entirely:

# Use Scoop (installs with proper PATH setup, no SmartScreen warning)
scoop bucket add gomodvanityurls https://github.com/gomodvanityurls/scoop-bucket
scoop install gvu

# Or use install.sh if you have a shell environment (WSL, Git Bash, etc.)
curl -fsSL gomodvanityurls.com/install.sh | bash

The SmartScreen warning will gradually disappear as more users install gvu.

How do I update gvu on Windows?

If installed via Scoop:

scoop update gvu

If installed via install.sh (WSL/Git Bash):

curl -fsSL gomodvanityurls.com/install.sh | bash

If installed manually: Download the latest .exe from GitHub Releases and replace the old file.