Troubleshooting

Connection refused on .prt.dev URLs

The router isn’t running, the CA certificate expired, or port forwarding (443 → 3001) is missing.

HTTPS worked before but suddenly stopped

The local CA certificate expires after one year. Treeline auto-renews when within 7 days of expiry, but if the router hasn’t run in a while, the cert may have lapsed.

Router version mismatch after upgrading the CLI

Since v0.40.1, brew upgrade git-treeline auto-bounces the router via brew’s post_install. If the warning still appears (older brew formula, manual install, or a non-brew install), bounce it explicitly. gtl serve restart is the fast path — no sudo, no plist rewrite.

Branch URLs broke after a reboot

macOS’s built-in pf service loads pf.conf at boot but does not enable pf, so the 443→3001 redirect silently disappeared after every restart. v0.40.1 ships a LaunchDaemon that re-enables pf at boot — existing installs need to re-run install once to pick it up. gtl doctor warns when the daemon is missing.

Safari can’t reach branch URLs

Safari does not resolve *.localhost to loopback. Switch to prt.dev (real DNS, works in all browsers) or sync hosts entries.

Login fails / CSRF token mismatch through the router

Before v0.35.4, the proxy did not set X-Forwarded-Proto. Rails compared Origin: https:// against request.base_url which returned http://, causing origin mismatches. Upgrade to v0.35.4+.

“Blocked host” error in Rails

Rails rejects requests whose Host header doesn’t match config.hosts. Whitelist the router domain.

env:
  ROUTER_DOMAIN: "{router_domain}"

config.hosts << ".#{ENV.fetch('ROUTER_DOMAIN', 'prt.dev')}"

Vite / Django allowed hosts equivalent

Vite: add server.allowedHosts: [".prt.dev"] to vite.config.js. Django: add .prt.dev to ALLOWED_HOSTS. gtl tunnel prints framework-specific hints when it detects a misconfiguration.

Changed .treeline.yml but the env file has old values

env: changes sync automatically on gtl start and gtl restart. If you manage the server yourself, sync manually.

Changed commands.start but the server runs the old command

The supervisor caches the start command at launch. Kill it and start fresh.

gtl link didn’t update the running app

Since v0.33.0, gtl link automatically regenerates the env file and restarts the supervised server. On older versions, run gtl env sync and restart manually.

“Port already in use”

Another process grabbed the port since the last allocation. Treeline detects this at setup time (v0.28.0+) and re-allocates. For existing worktrees, refresh.

Browser says ERR_UNSAFE_PORT

Browsers refuse connections to ports on the WHATWG blocked list (e.g. 6000, 6665–6669). Since v0.30.0, the allocator skips these. Run gtl refresh to re-allocate.

App starts but on the wrong port

Some frameworks (Vite, Next.js, Django) don’t read PORT for their listen port. Wire it into the start command. gtl doctor detects this.

commands:
  start: next dev --port {port}

commands:
  start: npx vite --port {port}

Deprecation warnings about old config keys

Treeline auto-migrates renamed keys on first load: setup_commands → commands.setup, start_command → commands.start, default_branch → merge_target, ports_needed → port_count. The old key is rewritten automatically.

Typo in .treeline.yml or config.json

Since v0.30.0, gtl doctor and gtl init detect unrecognized keys and suggest corrections with “did you mean?” based on edit distance.

createdb: ERROR: syntax error at or near "-"

A dash in project: or database.template: flows through {project}/{template} substitution and lands in an identifier Postgres rejects. v0.40.2 validates these at config load and prints a gtl rename <suggested> hint. gtl rename updates the registry, drops the old DBs, and re-runs setup so worktrees come back up under the sanitized name.

Existing ports conflict with new defaults after upgrade

v0.31.0 changed port.base from 3000 to 3002 and port.increment from 10 to 2. Existing allocations keep their ports. Run gtl refresh to re-allocate with the new defaults.

Registry references worktrees that no longer exist

When directories get deleted outside of gtl release, the registry is left holding orphan entries. v0.40.0 adds an audit and safe automatic repair that backs up the registry before pruning.

Many worktrees lost their allocation after a major upgrade

gtl reallocate bulk re-runs setup. Defaults to dry-run; pass --force to apply. Useful after registry repair or a Conductor-wide rebuild.