Skip to content

Troubleshooting

This guide provides solutions for common issues you might encounter when using or developing with gtb.

Installation & Environment

Private Modules (403 Forbidden / Terminal Prompts)

If you encounter errors fetching private modules (e.g., github.com), ensure your Go environment is configured to treat them as private.

go env -w GOPRIVATE=github.com

Also, ensure Git is configured to use your credentials for the private host:

git config --global --replace-all url."https://${GITHUB_USERNAME}:${GITHUB_TOKEN}@github.com".insteadOf "https://github.com"

"Command not found" after install

If you installed the tool via go install but cannot run it:

  1. Check that $GOPATH/bin is in your $PATH.
  2. Run go env GOPATH to find your Go workspace path.

Generator Issues

"Command is protected"

The generator will not overwrite commands marked as protected: true in the .gtb/manifest.yaml.

Solution 1: Explicitly Unprotect 

gtb generate command unprotect my-command

Solution 2: Use Force If you want to overwrite it just this once: 

gtb generate command --name my-command --force --protected=false

Corrupt Manifest

If .gtb/manifest.yaml becomes corrupted or invalid, the tool might panic or fail to resolve commands.

Recovery:

  1. Back up the current manifest.
  2. Run gtb regenerate manifest to rebuild it from your existing code.
  3. Verify the new manifest looks correct.

Linting Failures (golangci-lint)

The generator automatically runs golangci-lint run --fix after generating code. If this step fails (e.g., due to strict linter settings):

  1. The generated code is still saved to disk.
  2. Navigate to the generated file manually.
  3. Run golangci-lint run to see specific errors and fix them manually.

Runtime Issues

Configuration Not Loading

If your tool isn't picking up the configuration you expect:

  1. Check the search paths. By default, it looks in ~/.<toolname>/ and /etc/<toolname>/.
  2. Enable debug logging to see exactly what files are being loaded: 
    ./my-tool --debug command
    Look for logs indicating "Config loaded from...".

"Asset not found"

If you are getting errors about missing assets:

  1. Ensure you have run go mod tidy.
  2. Check that //go:embed assets/* directives are present in your main.go or command files.
  3. If developing locally, ensure the assets/ directory exists relative to where you are running the command.

AI Conversion Issues

Rate Limiting / 429 Errors

If the AI provider returns rate limit errors:

  1. Wait a few moments and try again.
  2. Check your API key quotas.
  3. Try a different model using the --model flag if supported.

"Generation failed" / Broken Code

If the AI generates code that doesn't compile:

  1. The generator will wrap the logic in a comment // AI generation failed... and return nil.
  2. Open the file and review the commented-out code.
  3. Manually fix the syntax errors or missing imports.
  4. You can try re-running with a refined prompt using --prompt.

Advanced Features

Auto-Update Failures

The "bait and switch" update pattern can fail in specific environments:

  • Permission Denied: Ensure the user has write permissions to the directory where the binary resides.
  • File Locked (Windows): If the update fails because the file is in use, try closing all instances of the tool and running the update command explicitly.
  • Network Timeouts: Check your connection to GitHub. You can increase the timeout by setting the HTTP_TIMEOUT environment variable.

VCS & Repository Issues

  • SSH Agent Conflicts: If NewRepo fails to find your keys, verify the agent is running (ssh-add -l).
  • Token Invalidation: If using GITHUB_TOKEN, ensure it hasn't expired and has the repo scope.
  • Memory Pressure: Large repositories pulled into SourceMemory (RAM) may cause OOM errors in resource-constrained environments (e.g., small CI runners).

Service Orchestration

  • A stop that hangs: a service's stop runs under the shutdown deadline and is abandoned when it passes, so Wait() returns. Outcome().Unfinished names each step that didn't finish; check that service's logs.
  • Signal collision: inside a GTB command, the root owns SIGINT/SIGTERM. Don't pass controls.WithSignals() to a controller there, or two handlers race on one Ctrl-C. To handle signals yourself, opt the root out with root.WithoutSignals().
  • The tool stays up after a service fails: without controls.WithStopOnGiveUp(), a service that fails for good (a panicking start included) leaves the process running but not ready. See How to manage background services.

Credentials & Keychain

  • "OS keychain" option missing from the init ai wizard. Expected when the current host has no reachable credentials Backend. KeychainAvailable() returning true but Probe() returning false means the backend is compiled in but unreachable: on Linux the usual cause is a session bus without a registered Secret Service provider (GNOME Keyring / KWallet). See Testing the keychain on a headless host for diagnostics and workarounds (dbus-run-session + gnome-keyring-daemon, containerised Secret Service, or the in-memory backend swap).
  • ErrCredentialUnsupported from credentials.Store / Retrieve / Delete. The stub backend is active: your tool's main hasn't blank-imported gitlab.com/phpboyscout/go-tool-base/pkg/setup/keychain (the framework's link) and hasn't registered a custom Backend via credentials.RegisterBackend. Add the blank import (gtb enable keychain writes cmd/<tool>/keychain.go) and rebuild, or register your own backend: see the custom-backend how-to.
  • Bitbucket resolver aborts with "not valid JSON" / "missing username or app_password". A configured bitbucket.keychain reference points at a corrupt or incomplete entry. Re-run the Bitbucket setup to rewrite the blob, or delete the keychain entry and fall back to bitbucket.{username,app_password}.env env-var references.
  • doctor credentials.no-literal warns after migrating to env-var or keychain mode. The warning fires if a literal *.api.key / auth.value / bitbucket.<field> is still present in config. Remove the stale literal; the .env or .keychain entry doesn't suppress it automatically.

Support & Feedback

Error Signposting

If your tool is configured with a HelpConfig, error messages will include a link to a Slack channel or support team. Refer to the link provided in the error output for project-specific assistance.