> ## Documentation Index
> Fetch the complete documentation index at: https://docs.groundforge.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Diagnose common SaaS platform, SDK, Channel, governance, and CLI issues.

Start with scope and identity. Confirm the Organization, Workspace, Agent, and credential before changing resource configuration.

## 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](/platform/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

```bash theme={null}
gforge context -o yaml
gforge doctor
```

Confirm the base URL is `https://platform.groundforge.ai` and that the saved Organization, Workspace, and environment are correct.


## Related topics

- [Mailgun](/guides/mailgun.md)
- [Request Tracing](/guides/request-tracing.md)