Troubleshooting

​

External Agent does not appear

• confirm the SDK process is running;
• use https://platform.groundforge.ai as the endpoint;
• check Organization and Workspace IDs;
• confirm the credential targets the stable external Agent ID;
• inspect SDK registration errors.

​

External Agent does not receive Channel jobs

• confirm serve=True;
• verify the Channel is attached and the Agent is published;
• confirm the Channel callback reached GroundForge;
• check that the Agent credential is active;
• send a Channel dry run with the exact command in Channels.

​

Channel delivery fails

• copy the generated callback URL again;
• check provider signature settings;
• run gforge channels test <channel-id> ... --dry-run -o yaml;
• run the same test without --dry-run;
• inspect the Trace and Channel output separately.

​

Discovery fails

• keep an external Agent running while requesting a fresh Agent discovery;
• verify tool names, descriptions, and schemas are serialisable;
• test remote MCP connectivity and authentication;
• use --preview before uploading local stdio discovery.

​

Gateway result is unexpected

• open the Gateway and confirm the selected Agent or MCP provider;
• confirm the capability name matches the latest discovery;
• inspect the stored action;
• open the Trace and check whether the result was Allow, Observe, Review, Block, or unavailable.

​

CLI cannot authenticate

gforge context -o yaml
gforge doctor