Skip to content
Scalpels home

Scalpels is officially launching on October 31, 2026. Special early adopter pricing is available now.

← All documentation

Documentation

Hone

Troubleshooting

Updated

Most Hone problems are one of three things: an app is not actually sending, the Hone queue is not processing what arrives, or the hourly rollup has not run. Start with ingest-freshness-tool, which reports per-app freshness, client losses, aggregate freshness and maintenance health in one answer.

An app is not reporting

The client is fail-open and silent, so a connected-looking app can send nothing.

  • The pull request is not merged or deployed. Scalpels writes the environment values when you attach, but the app reports only once the client packages are installed and deployed. Merge the scalpels/connect-hone pull request after committing composer.lock, then deploy.
  • The transport was not replaced. In the app, run php artisan tinker --execute='echo get_class(app(\Laravel\Nightwatch\Core::class)->ingest), PHP_EOL;'. It must print ArtisanBuild\HoneClient\HoneIngest. If not, check that both HONE_URL and HONE_TOKEN are set and run php artisan config:clear. With only one of them set, the client logs Hone is half-configured: set both HONE_URL and HONE_TOKEN, or neither. and sends nothing.
  • Nightwatch is off. NIGHTWATCH_ENABLED must be true.
  • HONE_URL is the base URL. It must end in /ingest. Posting to the base URL fails silently.
  • The app is not on Laravel 13. composer update cannot install hone-client on Laravel 11 or 12. Upgrade the app first.
  • Laravel Cloud's Nightwatch integration is on. Turn it off. It sends telemetry to Nightwatch's hosted service instead.

Ingest returns 401

The credential is missing, revoked, expired, or is not an ingest credential. Hone accepts only an installation-type bearer credential with the ingest purpose; an MCP credential is refused here. List credentials with GET /bfc/credentials to check its status. If the app was attached through Scalpels and its credential is gone, see "Credential already issued / repair required" in Attach to an existing app.

Ingest returns 422

Authentication passed but the batch did not. The response body says why. The one to recognise is:

Envelope v2 is newer than this Hone server (max v1). Upgrade your Hone app.

That means an app's client is newer than your Hone server. Upgrade Hone, let its migrations run, and only then update clients. Run php artisan hone:update in an app to see whether its client and the server agree.

The MCP endpoint returns 401

  • You are using an ingest credential. Ingest and MCP credentials are not interchangeable; mint a separate one with the mcp purpose. See Connecting your agent.
  • The credential was revoked, or was rotated and its one-hour grace window has passed.

The agent sees only 15 tools

tools/list is paginated and the first page has 15 tools. A client that does not follow the cursor shows only those. All 24 tools are still callable by name.

Events arrive but tools return nothing

  • The queue is not draining. Accepted batches wait on the queue. On a Scalpels install they use the managed queue; if you set HONE_QUEUE_CONNECTION, remove it so batches use the default connection.
  • The rollup has not run yet. Most tools read daily aggregates, which the hourly hone:maintain builds. Check aggregate_freshness in any answer, or run php artisan hone:rollup on the environment.
  • The events are old. Each rollup covers UTC days from 24 hours ago through today by default. An event whose timestamp falls before that is stored but never aggregated unless you run hone:backfill for its date.

hone:health alarms

Run php artisan hone:health --json on the environment.

  • maintenance means the hourly maintenance run has stopped succeeding. Check that the scheduler is on for the environment and read the scheduler logs.
  • retention means raw events are older than they should be, which usually follows from the first.
  • aggregate_freshness means the newest daily aggregate is stale.
  • idle is not a failure. No event has arrived recently, so the checks are not judging.

After maintenance recovers, fill any gap with php artisan hone:backfill <from> <to> while the raw events for those days are still retained.

Hone does not alert you when a check fails. You see it only by running the command, reading the scheduler logs, or asking your agent.

The app id is not the name you expected

Hone names an app after its credential, not after HONE_APP or APP_NAME. Apps attached by Scalpels appear as their Cloud environment id, or as forgesite- followed by the Forge site id. Use list-apps-tool to map ids to apps.

An agent can see apps you did not expect

That is how MCP credentials work. A credential reads every app reporting to that Hone deployment; there is no per-app MCP credential. If someone should see only one app's telemetry, that app needs its own Hone deployment.

No deploys to compare

deploys-tool lists only deploy ids that apps actually sent. Set NIGHTWATCH_DEPLOY in each app on every deploy; records sent without it have no deploy.