Troubleshooting
Start with atfg --version, atfg whoami and atfg doctor. Keep the failed command, request/deployment/run ID and error text when asking for help. Never include credentials or session files.
Download denied
Check gh auth status and repository access. For Homebrew, export HOMEBREW_GITHUB_API_TOKEN from gh auth token --hostname github.com in the current shell.
npm additionally needs package-registry authentication. A GitHub Packages 403 about token lifetime means the token exceeds the organization's policy; use an allowed expiry and authorize SSO if required. See npm installation.
Wrong atfg version
An older binary can take precedence on PATH. For Homebrew:
"$(brew --prefix)/opt/atfgraph/bin/atfg" --version
export PATH="$(brew --prefix)/opt/atfgraph/bin:$PATH"
For the script installer, the normal location is ~/.atfgraph/bin/atfg.
Python says the SDK is missing
atfg doctor --local
atfg build
These use the managed SDK. A system python3 import failure does not prove it is missing. If the managed environment fails, repair the installation with the original installer or brew postinstall fclimited/atfgraph/atfgraph.
Console has no teams
Quit Console, sign in with the new CLI on the same computer, and reopen it. Check account and membership. A VM/container session is separate from the Mac session. Check atfg doctor before reinstalling the app.
Sign-in port occupied
A container or VM may be forwarding 8020. Stop that forwarding temporarily, complete host sign-in, then resume it.
Team request exits with code 3
The request is pending approval. Check atfg approvals --all and the named approver. Do not submit duplicates or approve your own request.
Rollout could not start
This can happen before node deployment, for example when the graph service is unavailable. Ask the platform owner to recover the service, then retry the same release. Bumping the version does not repair service availability.
Node exists but no run appears
Confirm deployment is healthy, then invoke the capability. Select the same team and environment in Console and match the run ID. Registering, building, deploying and running are distinct steps.
Nested nodes or test collisions
Keep nodes in sibling directories. Move a nested node out of the other node's source directory before rebuilding, and check the release file list.
macOS blocks Console
Current builds lack Apple notarization. Use the normal per-app Open Anyway control for the release you installed. Do not disable system-wide protection.
Linux loader error
A message such as libdbus-1.so.3: cannot open shared object file happens before the CLI can run. Install the matching OS runtime dependency or use a supported environment. Login and Python packages do not fix native loader errors.
Claude cannot see the plugin
Run claude plugin list in the same environment where Claude Code runs. A plugin installed inside a VM is separate from your host installation. Follow the Claude Code registration steps and restart Claude after installation. Avoid mixing an old local plugin copy with the current installed marketplace version.
Build fails: choose the failed check
| Failed check | What to inspect |
|---|---|
| Manifest | Node name, version, entrypoint and capability declarations in agentnode.yaml. |
| Dependencies | Pinned requirements and whether the installed managed SDK/tools pass atfg doctor --local. |
| Secret files | The reported files and .atfgignore; remove credentials from source before packaging. |
| Tests | The failing assertion and input. Fix the node behavior or expectation before retrying deployment. |
| Lint | The reported file and rule. Apply the targeted fix, then rerun atfg build. |
A successful build proves local checks passed. Deployment health and a successful hosted run are separate checks.
Console says a route needs admin access
A route error is not proof that the entire graph service is down. Record the page and error, confirm the selected team/environment and check whether ordinary runs load. Some framework features need platform enablement or privileged access. Ask AI-LAB to confirm the supported hosted workflow; do not paste a server admin token into the app or follow legacy key-icon instructions blindly.
Request accepted, but nothing finished
--no-wait returns before the result. Check atfg --team <team> --env dev status <node> for a deployment, or inspect the returned run ID in Console. A pending approval needs the named approver before work continues. See the CLI exit codes.
Still blocked?
Use Get support for who to contact and a short diagnostic template. Keep the original command, time and identifiers; avoid repeated installs or new release versions until the failure is understood.