Troubleshooting

Use this guide when something did not work and you need the shortest path to the owning surface.

Start by deciding whether the failure happened before work started or after work started.

First split

Debug order

1. Check Settings for identity, account access, model defaults, CLI tokens, connections, and GitHub account state.
2. Check Installations for GitHub App coverage.
3. Check Projects for repo visibility, repo settings, and sandbox launch state.
4. Check Agents for slug, model, prompt, category, skills, rules, and context.
5. Check the route source: Triggers, Assignments, or Automations.
6. Check Slack when Slack is the source surface.
7. Check Observability only after a run exists.
8. Check Sandboxes when a preview/runtime is involved.

Repo is visible but events do not fire

Visibility and triggerability are different.

1. Open Installations.
2. Confirm the repo owner is covered by the Mogplex GitHub App.
3. Confirm the route is on the same installation or repo that owns the event.
4. Confirm the route is enabled, or the automation is published.
5. If work starts, continue into Observability.

Do not tune the agent prompt until App-backed coverage is healthy.

Mention routing fails

Check the exact comment text first.

@mogplex
@mogplex/triage

Rules:

• bare @mogplex needs a default mention route
• targeted @mogplex/<slug> needs an agent slug match
• @mogplex triage is not targeted
• PR or issue comments without @mogplex are normal comment events, not mention events

Read GitHub Mention Routing for the full model, or use GitHub Routing Cookbook for concrete route recipes.

Slack mention starts the wrong behavior

Slack and GitHub mentions have different routing models.

For Slack:

• @mogplex in a linked channel starts a repo-agent run
• @mogplex in an unlinked channel stays conversational
• DMs stay conversational
• thread replies continue an existing Slack-backed conversation

If Slack replies conversationally when you expected repo work:

1. open Slack
2. confirm the workspace is installed
3. confirm the channel is linked to the target repo
4. confirm repo-agent runs are enabled
5. confirm the Slack user is mapped and allowed
6. check the monthly run limit
7. if a run starts, continue into Observability Runbook

Model is missing

Start with Available Models.

Check:

• whether the model is visible in the live catalog
• whether the model is enabled for the account
• whether the account plan includes access to that model
• whether the agent is pinned to a hidden legacy model
• whether a repo or route excludes the model
• whether the CLI has synced the expected hosted state

Use API Models only when you need the route behavior, not the user-facing picker explanation.

Use Model Selection and Cost when the model exists but the route, agent, repo, or cost policy is unclear.

CLI state looks wrong

Start with CLI Authentication and Configuration and Flags.

Check:

• the signed-in account shown by the CLI
• local ~/.mogplex auth and permission state
• environment variables overriding expected config
• whether hosted model defaults or MCP definitions are synced as expected
• repo-local permission rules when tool approvals feel surprising

Use the app Settings page to confirm the hosted account state that the CLI should inherit.

Sandbox or preview is unhealthy

Start from Projects if repo settings may be wrong.

Start from Sandboxes if a runtime already exists and you need to inspect, stop, delete, or open the exact instance.

Check:

• root directory
• install command
• dev command
• dev port
• environment mapping
• managed sandbox access
• optional linked Vercel team and project metadata
• sandbox timeout
• active branch and preview URL

Use Observability when you need the linked run, call, tool, cost, or error trail.

Use Sandbox Setup Checklist when launch settings are still uncertain.

API request fails

Start with API Authentication and API Errors.

Check:

• whether the route accepts PAT auth or requires a browser session
• whether the token has read or write scope
• whether the request expects the v1 run API envelope or a product route shape
• whether idempotency keys are being reused with a different body
• whether the response error code is retryable

Use Working Requests for known-good examples. Use API Quickstart for the shortest complete path from token to repo lookup, run start, event inspection, cancellation, and sandbox listing.

What to capture before escalating

• repo owner/name and repo ID if available
• GitHub owner coverage state from Installations
• route source: CLI, Trigger, Assignment, Automation, API, or GitHub mention
• Slack workspace and channel link state when Slack started the work
• exact GitHub event or comment text
• agent slug and model
• run ID, sandbox ID, or API response body
• first error message, not only the final retry
• whether Observability has any matching record

Read next