Troubleshooting

Troubleshooting

Find the message you see, then read the cause and the fix. Messages are quoted from the source; ... marks a part that varies.

The server will not start

Message	Cause	Fix
`refusing to start: no session signing key configured`	`PULSE_JWT_SECRET` is unset	Set it to a new random value. There is no default.
`refusing to start: the pulse appfs root cannot be mounted: ...`	The sealed app root has no usable backend	Check the object store settings, or `PULSE_APPFS_DIR` for a local root.
`Failed to initialize database: ...`	Usually `CORE_ENVELOPE_KEK` is missing; the database refuses to open without it	Project the key.
`refusing to start in production: insecure configuration: ...`	`PULSE_ENV=production` and a check failed	Fix each listed problem, or serve the app same-origin with `PULSE_WEB_DIR`.
`TLS misconfigured: set BOTH PULSE_TLS_CERT and PULSE_TLS_KEY (or neither)`	Only one of the two is set	Set both, or neither.
`MESH_MTLS=true but mesh identity unavailable: ...`	The mesh CA could not be loaded	Provide `MESH_CA_CERT` and `MESH_CA_KEY`, or turn off `MESH_MTLS`.
`AudioSocket failed to bind and ARI IS configured ...`	Outbound calling is configured but the audio listener cannot bind	Free `AUDIOSOCKET_ADDR`, or clear the ARI settings.
Server exits with no output, no log file	Locally: `pkill -f 'pulse-server serve'` killed your own shell, or a bare `&` job was reaped	Kill by PID. Start the server in a real background mode.
`address already in use`	A previous server holds the port	Stop it by PID, then restart.

An unknown EMBEDDING_FORMAT also stops the server at startup. Use qwen3-embedding, nomic-v1.5, or raw.

Signing in

Message	Cause	Fix
`invalid credentials`	Wrong username or password; you used your email instead of your username; or no break-glass admin was seeded	Sign in with the username. On a local server, start it with `PULSE_ADMIN_PASSWORD`.
`authorization token is not provided`	The call had no bearer token	Send `authorization: Bearer <accessToken>`.
`invalid token: ...`	The token expired, was signed out, or is from before server-side sessions	Sign in again.
`token contains an invalid number of segments`	A script read `.token`; the field is `accessToken`	Read `accessToken`.
`google sign-in not configured (GOOGLE_CLIENT_ID unset)`	Google sign-in is off	Set `GOOGLE_CLIENT_ID`.
`google sign-in is not available on this instance`	`AUTH_ALLOWED_EMAILS` is empty	Add the allowed addresses.
`this account is not authorized for this instance`	The email is not on the allowlist	Add it to `AUTH_ALLOWED_EMAILS`.
`license expired or invalid`	A configured licence failed verification	Install a valid licence.
Log: `AUTHENTICATION DISABLED — every request will be rejected as Unauthenticated`	The session key is one authz refuses, such as a published value	Replace `PULSE_JWT_SECRET`.

AI features

Message	Cause	Fix
`inference server is not running` / `model service is not ready — the inference server is not running`	No inference server, or it is still loading	Check `INFERENCE_REMOTE_URL` or the local model files. Watch `model_ready` on `/health`.
`the inference plane is at capacity and declined this request; nothing was generated — retry in a few minutes`	Admission control refused the call	Retry later, or raise `PULSE_ADMIT_MAX`.
`the configured generation deadline cannot pay for a usable answer: ... Nothing was dispatched.`	The time budget is too short for the decode rate	Raise `PULSE_GENERATION_TIMEOUT_SECONDS`, serve a faster model, or ask for less.
`the model returned no content for ...`	The model produced an empty response	Retry. Check the inference server’s log.
`still-image generation is not available: the image-generation tier was retired ...`	Still images are not supported	Request a video `format` instead.
`grounding INACTIVE: ...` in the log	The embedding endpoint is missing or unusable	Set `EMBEDDING_URL` to an embeddings server. Generators still run, but say they are ungrounded.

Site Audit

Message	Cause	Fix
`could not read ... — a reachable website with readable content is required to run the diagnostic`	PULSE could not load the site	Check the URL is public and returns readable HTML.
`url is required` / `repo_path is required`	A field is missing in `ApplyAuditActions`	Fill it in.
`apply modes are disabled on this server; set PULSE_APPLY_ENABLED=true (exactly, lowercase) to allow write/commit/pr`	The kill switch is off	Use `plan`, or have an admin arm it.
`github integration is missing a target owner/repo — ...`	`pr` mode without a target	Set `owner` and `repo` on the GitHub connection.
`scoring config: ...`	`PULSE_SCORING_CONFIG` is unreadable or invalid, or the profile is unknown	Fix the file or the profile name.

Leads and connections

Message	Cause	Fix
`HubSpot isn't connected yet — configure it on the Integrations page first`	No HubSpot connection	Add it under Integrations → Data sources.
`HubSpot integration has no access token configured`	The connection has no token	Rotate the credential.
`HubSpot sync failed: ...`	HubSpot rejected the call	Check the token’s scopes.
`unsupported lead platform: ... (only hubspot is supported today)`	`SyncLeads` with another platform	Use `hubspot`.
`a niche is required to prospect for leads`	`ScrapeLeads` without a niche	Provide one.
`a lead needs at least a name, email, or company`	Empty `CreateLead`	Fill one in.
`invalid pipeline stage "..." (want new\|contacted\|qualified\|won\|lost)`	Unknown stage	Use one of the five.
`outbound calling isn't configured — set up Asterisk and ...`	ARI settings missing	See Telephony and messaging.
`lead has no phone number`	Nothing to dial	Add a phone number.
`Google Analytics isn't connected yet — configure it on the Integrations page first`	No GA4 connection	Add it under Integrations → Accounts.
`no GA4 property ID configured — set it when connecting Google Analytics`	The connection lacks a property ID	Reconnect with the property ID.
`not enough synced GA data to forecast (... days, need at least 4) — sync more history first`	Too little cached data	Run `SyncGaData` with a longer lookback.

Publishing

Message	Cause	Fix
`website publishing is disabled: ...`	The blog channel is not armed	See Publishing controls. The message names the layer.
`PULSE_SITE_REPO is not set — refusing to publish; set it to YOUR site repo as owner/repo`	No target repository	Set `PULSE_SITE_REPO`.
`no github integration/token configured for user ...`	The content owner has no GitHub connection	Add one under Data sources.
`no publishing integration for channel ... yet`	The channel has no publisher, for example Facebook or X	Nothing to fix; that channel cannot publish.
A scheduled post shows `withheld`	Its channel was disarmed when it came due	Arm the channel, then schedule the content again.
Log: `PUBLISHCFG-AMBIGUOUS PULSE_APPLY_ENABLED=...`	The value is not exactly `true`	Write `true`, lowercase.

Voice, billing, media

Message	Cause	Fix
`voice calling is not configured: CALLING_AGENT_URL is unset` (HTTP 503)	No calling agent	Set `CALLING_AGENT_URL`.
`speech synthesis is not configured`	No speech engine is attached	Check the server log at startup.
`media storage is not available: ...` / `media unavailable`	The sealed media store is not mounted	Check the app root’s backend.
`no subscription is on record for this deployment (TENANT_ID is not projected); ...`	Deprecated `MeteringService` without a tenant	Set `TENANT_ID`, and use `BillingService/GetOverview`.
`compute-unit consumption is not metered by PULSE; ...`	`GetResourceUsage` is not implemented	Expected. PULSE does not meter usage.
Log: `Site Audit Engine: NOT started — no target site; ...`	No daily audit target	Set `PULSE_SITE_AUDIT_URL`.

The app looks empty

Insights and Impact Analytics show zeros. Expected: no connector fills the per-channel metrics table yet. See Follow up and measure.
Approval, Campaigns, and Follow-up are empty. Run a Site Audit. A finished diagnosis fills them.
The web app screenshots blank in headless Chrome. It renders with CanvasKit, which does not paint under headless software rendering. Drive the backend over gRPC instead.