TopGun/ Help Center/ Troubleshooting

Troubleshooting

Diagnose and fix the most common TopGun issues. Each entry shows the symptom, cause, and step-by-step fix.

Quick diagnosis: inspect ~/.topgun/state.json to see the last completed stage, then open the latest found-skills-<hash>.json or audit-<hash>.json artifact to confirm registry coverage and audit status.

Registry Unavailable / 3+ Registries Down

Registry timeout or connection error
Warning
Symptoms
TopGun › ⚠ skills.sh timed out after 10s — skipping TopGun › ⚠ 3 or more registries failed — connectivity warning TopGun › ✓ Found 3 candidates across 2 registries (reduced coverage)
Cause

One or more registry adapters did not respond within the 10-second timeout. This is typically a temporary network issue or registry downtime. TopGun continues with the adapters that succeeded.

Fix
  • Wait and retry. Most registry outages are brief. Run the same /topgun command again in a few minutes.
  • Check your internet connection. Confirm you can reach skills.sh and github.com from a browser.
  • Use --offline with cached results. If you ran a similar query recently, /topgun <task> --offline uses cached registry data and skips all live requests.
  • Restrict to reachable registries. Use --registries to target only the registries that are online: /topgun <task> --registries npm,smithery.

SENTINEL File Missing from Plugin

Bundled SENTINEL file not found inside TopGun plugin
Pipeline abort
Symptoms
TopGun › ✗ Cannot Read $CODEX_PLUGIN_ROOT/skills/sentinel/SKILL.md TopGun › Bundled SENTINEL v2.3.0 missing from plugin TopGun › Pipeline aborted at SecureSkills stage
Cause

SENTINEL ships bundled directly inside the TopGun plugin at skills/sentinel/SKILL.md. If that file is missing, the plugin cache is corrupted or incomplete. The SecureSkills stage cannot run without it.

Fix
  • Refresh TopGun. If TopGun still appears in the picker, run /topgun-update to rebuild the local cache. If it does not, reinstall from the official Codex marketplace source: codex plugin marketplace add https://github.com/alo-labs/codex-plugins.git.
  • Verify the bundled file exists. After refresh, check that a versioned cache path such as ~/.codex/plugins/cache/*/topgun/<version>/skills/sentinel/SKILL.md is present.
  • Clear stale cache. If refresh still fails, remove the broken TopGun cache tree under ~/.codex/plugins/cache/ and reinstall.

Install Failure

The plugin install step fails or silently does nothing
Install error
Symptoms
TopGun › ✗ /plugin install returned non-zero exit TopGun › Falling back to local-copy install method… TopGun › ✓ Skill installed via local-copy fallback
Cause

There is a known intermittent failure mode in the plugin install step where a valid install request exits non-zero or does not persist. TopGun detects this and automatically falls back to a local-copy install: it copies the audited SKILL.md directly to the Codex skills directory.

Fix
  • Trust the fallback. The local-copy fallback installs the same audited skill content. The SENTINEL audit result applies equally to both install methods. If you see "installed via local-copy fallback", the skill is functional.
  • Verify the skill is active. After a local-copy install, the skill should appear in the skill picker or respond to a direct invocation. If it does not, run /topgun <task> --reset to retry the full pipeline.
  • Refresh TopGun's local install state. If the picker still does not show the skill, run /topgun-update or reinstall from the official Codex marketplace source.
  • Check the install registry. Inspect ~/.topgun/installed.json and ~/.topgun/state.json to confirm which install method succeeded.

Pipeline Resume Issues

Resume picks up stale state from a previous query
Unexpected behavior
Symptoms
TopGun › Resuming from state.json (stage: CompareSkills) TopGun › Query: "git automation" — but I asked for "test runner"
Cause

TopGun's resume logic checks for any existing state.json at startup. If a previous pipeline was interrupted and never completed, it will resume — even if your new query is different.

Fix
  • Use --reset to start fresh. Run /topgun <your task> --reset to discard the stale state and run a new pipeline from the beginning.
  • Or clear state manually. Delete ~/.topgun/state.json, then run your /topgun command normally.
Resume skips FindSkills but registry coverage has changed
Info
Symptoms
TopGun › Resuming from state.json (stage: SecureSkills) TopGun › Skipping FindSkills and CompareSkills — already completed
Cause

This is expected behavior. When resuming, TopGun skips completed stages. If you added a new registry token or want to search with updated coverage, use --reset to run fresh.

Fix
  • If you want fresh registry results (e.g. after adding a GitHub token), run with --reset.
  • If you're happy to continue auditing the previously selected winner, let the resume proceed — it will run SENTINEL from where it left off.

Auth Token Issues

GitHub rate limit hit — reduced candidate coverage
Warning
Symptoms
TopGun › ⚠ GitHub adapter: rate limit reached (60 req/hr) TopGun › ⚠ GitHub results may be incomplete
Cause

The GitHub adapter uses the unauthenticated API by default, which is limited to 60 requests per hour. In heavy use, this limit is quickly exhausted.

Fix
  • Add a GitHub token. Create a personal access token with read:public_repo scope at github.com/settings/tokens, then store it: node topgun-tools.cjs keychain-set github_token <token>.
  • Authenticated limit is 5,000 req/hr — sufficient for any TopGun usage pattern.
Token stored but registry still returns unauthenticated results
Info
Symptoms
TopGun › ⚠ GitHub adapter: using unauthenticated API # Even though you set a token
Cause

The token may have been stored under the wrong service name, or under a different Keychain account. TopGun reads tokens at pipeline start, so the next /topgun run will pick up a newly stored value without restarting the app.

Fix
  • Verify the token is stored correctly. Run node topgun-tools.cjs keychain-get github_token — you should see a JSON payload with "found": true.
  • Rerun the pipeline. Start a fresh /topgun invocation, or use --reset if the previous run already passed the FindSkills stage.
  • Re-set the token. If keychain-get returns {"found": false}, run keychain-set again and confirm the Keychain permission dialog if one appears.
← Previous Command Reference