Troubleshooting¶
Start with php artisan mcp-hub:status and php artisan mcp-hub:doctor --online. Record the error code, time, and trace ID; exclude secrets and business payloads.
| Symptom | Check | Action |
|---|---|---|
| Doctor or health returns 503 | Is security metadata present? | Review the dry run and execute package migrations |
| Empty tool catalog | Are the registry and grants enabled? | Implement the resolver and policies, review resources, then sync |
| Source catalog unavailable | Is the manifest valid and reachable? | Fix the source; failed refreshes do not use stale grants |
| Source returns 401 | Do app tokens match on both sides? | Review provisioning without printing tokens |
| User operation returns 403 | Are delegation, actor, policy, and profile valid? | Check current account, tenant, and permissions |
| Settings or chat returns 403 | Are host Gates and guard available? | Define Gates using host permissions |
| Web mutation returns 419 | Do the session and CSRF token belong to the same application? | Fix session and origin handling; do not disable CSRF |
| Pairing interrupted | Was the encrypted proof saved? | Run connect --resume |
| Replacement has no effect | Do old environment values override the bundle? | Review pinned configuration through the operator |
| Models missing or denied | Are allowlists and budgets configured? | Configure application model access |
| Proposal conflicts or expires | Did the record version, policy, or expiry change? | Prepare a new proposal and request approval again |
| Export remains pending or fails | Are the worker, queue, and storage ready? | Fix the worker; crashed jobs need a new request and key |
| Download returns 409 | Did the data or grant snapshot change? | Create a new export |
| Download returns 410 | Has the TTL expired? | Create a new export |
| Composer conflict | Are PHP, framework, and Guzzle constraints compatible? | Review solver output and the lock file without security or platform bypasses. Package 1.0.0 needs Guzzle 7; on a fresh Laravel 13 (Guzzle 8) require 1.0.1 or later |
Pairing works, doctor --online shows operation: FAIL |
Is the package 1.0.0? | 1.0.0 sends an Origin the Hub's /mcp rejects. Update the package, or add the Laravel source URL to the Hub's ALLOWED_ORIGINS |
| Chat says it cannot create or change data | Does the message ask for the change? Does the client key allow writes? | Ask with a verb such as "buatkan", "ubah", "batalkan", "create"; turn on write for the app's key under Access |
| App login returns 429 after Hub activity | Does a host route use plain throttle:N,M? |
Package 1.0.1 uses its own counters; on 1.0.0 give host throttles a named prefix |
Distinguish URLs and credentials¶
MCP_HUB_URL points to the Hub's /mcp endpoint. MCP_HUB_BASE_URL points to the source. The client key authenticates Laravel to the Hub; the app token authenticates the Hub to Laravel. The delegation secret signs actor context and is not a general API token.
Worker checks¶
Web and queue workers must use the same release, configuration, APP_KEY, database, and private filesystem. Restart workers through the host's deployment procedure after changes. Refresh cached configuration through a controlled deployment process.
Issue reports¶
Include package and server versions, PHP and Laravel versions, the error code, and reproduction steps using synthetic data. Identify whether the case comes from a unit test, simulation, staging, or production. Remove tokens, codes, user identities, internal addresses, and business records from public reports.