Skip to main content

Troubleshooting

What to do when the CLI, library, or MCP server isn't behaving.

Step one: fibe doctor​

fibe doctor

The first thing to try, always. It checks:

  • Whether you can reach the Fibe API.
  • Whether your active profile / FIBE_API_KEY is valid.
  • Basic environment sanity (binary version, OS, network).

The output points at the actual problem. If fibe doctor is green, the cause is in your code or in the resource you're calling against, not in the SDK setup.

Verbose logging​

--debug makes the CLI dump every HTTP request, response, retry, and circuit-breaker event:

fibe --debug playgrounds create --name "x" --playspec 5 --marquee next

For the Go library, turn on debug logging:

client := fibe.NewClient(
    fibe.WithAPIKey(key),
    fibe.WithDebug(),                          // log HTTP traffic to stderr
    // or: fibe.WithLogger(slog.New(handler))  // send logs to a custom destination
)

For the MCP server, use the same global flag: fibe --debug mcp serve (in a client config, add "--debug" to the args array).

Structured errors​

--explain-errors makes the CLI emit a JSON error description instead of a friendly message:

fibe --explain-errors playgrounds get does-not-exist

The structured output includes the error code, HTTP status, request ID, and any validation details — enough for an agent to decide whether to retry or change the payload.

Common errors​

"no credentials"​

FIBE_API_KEY isn't set and there's no active profile. Run fibe login or set the env var.

"401 Unauthorized" / "403 Forbidden"​

Your credentials are wrong, expired, or scoped too narrowly. Check:

fibe auth status     # who am I supposed to be
fibe doctor          # does the API agree

If the scope is wrong, mint a key with the right scopes in API keys.

"429 Too Many Requests" / rate limited​

The Fibe API enforces per-account rate limits. The Go library auto-respects the retry-after header; the CLI surfaces a clear message. If you hit this consistently:

  • For automation, slow down or batch (use fibe_pipeline instead of many separate calls).
  • For interactive use, wait a minute.
  • If you genuinely need a higher limit, contact support.

"circuit breaker open"​

The library opens a circuit when the upstream is sustained-failing. It re-attempts periodically. If it stays open more than a few minutes, something is wrong with the API or your network. Run fibe doctor again.

"validation failed: missing required field"​

The resource creation or update is missing a required field. Use schema introspection to see what's needed:

fibe schema playspec | jq '.properties | keys'

Or fibe playspecs create --help for a CLI-formatted version.

"broken pipe" / "connection reset" mid-stream​

The Playground or Trick has stopped emitting data. For playgrounds logs --follow, this usually means the service ended. Run fibe playgrounds status to confirm.

Sending a message to a Genie fails (422)​

Message delivery fails with a structured 422 whose error code tells you what to do (--explain-errors surfaces it):

  • AGENT_BUSY — the Genie is mid-turn. Retry, or send with a queue busy-policy.
  • NEED_AUTH — the Genie needs to re-authenticate: fibe agents authenticate <id>.
  • AGENT_RUNTIME_NOT_RUNNING — start the chat first: fibe agents start-chat <id>.
  • AGENT_RUNTIME_UNREACHABLE / AGENT_RUNTIME_ERROR — check the Marquee and fibe agents runtime-status <id>.

MCP: "Authorization required" but the agent set a header​

Double-check the server was started with --http host:port (add --streamable for streamable HTTP) — plain stdio ignores Authorization headers and uses the host's profile.

MCP: tools list is empty​

Likely one of:

  • FIBE_MCP_TOOLS is set to a tier with no tools.
  • The MCP server isn't running (check the client's logs).
  • The client's MCP config points at the wrong binary path.

Schema introspection​

When you don't know what shape a resource takes, ask the API:

fibe schema --list                  # discover resource names and operations
fibe schema playground              # JSON schema for one resource
fibe schema playground create       # schema for one operation's payload
fibe schema playspec | yq '.properties.metadata'  # drill down

For agents, the same is exposed as fibe_schema. Use it liberally before composing a fibe_resource_mutate call.

Looking up a specific tool's error​

Every MCP tool's detail page (see the Tools catalog) documents the errors it can return. The --explain-errors flag on the CLI does the same.

"Help me figure out which command to run"​

fibe docs            # print the full CLI help for every command (pipe it into grep / your agent)
fibe help            # CLI help
fibe schema --list   # resource families
fibe doctor          # is auth/setup OK

From an MCP client, the equivalent tools are fibe_help, fibe_schema, fibe_doctor, fibe_tools_catalog.

When to file a bug​

If fibe doctor is green, your scopes are right, and you've tried with --debug and a fresh fibe login — and the same call works through the web UI but fails via the SDK — that's a real bug. Open an issue with:

  • fibe version
  • fibe doctor output
  • --debug output of the failing call (redact the API key)
  • The expected vs actual behavior

When you're stuck​

Sometimes the fastest answer is a Genie. Open one of your AI assistants with access to the reference library, give it the error message, and have it walk the relevant tool docs. The MCP server's tools (especially fibe_doctor, fibe_status, fibe_schema, and fibe_help) are designed for exactly this — they let an agent figure out the platform with you.

Last updated on