Skip to content

tutorials

Intended Documentation

Troubleshooting

Troubleshooting index for common Intended issues — organized by category with symptoms, causes, and resolution steps.

beginner6 min readimplemented

Troubleshooting#

This page covers common issues you may encounter when working with Intended, organized by category. Each entry includes symptoms, likely causes, and resolution steps.

Tip

Before diving into specific issues, check the service health endpoints. Many problems are caused by transient service unavailability. Run meritt health --all to get a quick status overview.

API Issues#

401 Unauthorized on every request#

Symptoms: All API calls return 401 Unauthorized, regardless of endpoint.

Likely causes:

  • API key is invalid, expired, or revoked
  • The Authorization header format is wrong

Resolution:

Verify header format

Ensure you are using the Bearer scheme:

bash
curl -H "Authorization: Bearer $API_KEY" \
  https://api.intended.so/health

A common mistake is omitting Bearer or including extra whitespace.

Check key validity

Verify your API key has not been revoked:

bash
meritt auth whoami

If this returns an error, generate a new key from the dashboard or CLI.

403 Forbidden on specific endpoints#

Symptoms: Some API calls work but others return 403 Forbidden.

Likely causes:

  • Your API key lacks the required scopes for the endpoint
  • Your tenant does not have access to the requested feature

Resolution: Check the scopes attached to your API key with meritt auth whoami --verbose. Compare against the required scopes listed in the API reference for the endpoint you are calling.

429 Too Many Requests#

Symptoms: Requests intermittently fail with 429 status and a Retry-After header.

Likely causes:

  • You are exceeding the rate limit for your tenant tier
  • A burst of requests triggered the per-second limit

Resolution: Implement exponential backoff with the Retry-After value. If you consistently hit rate limits, contact support to review your tier allocation.

Policy Issues#

Intent denied unexpectedly#

Symptoms: An intent you expect to be allowed is denied. The response includes "result": "deny".

Likely causes:

  • No matching allow policy exists (default deny)
  • A deny policy is matching before the allow policy
  • The policy is in draft status and not yet active

Resolution:

Check the deny reason

Examine the evaluation response for the reason field:

json
{
  "result": "deny",
  "reason": "no_matching_policy",
  "evaluated_policies": []
}

If evaluated_policies is empty, no active policy matches the intent.

List active policies

Verify the policy you expect to match is active:

bash
meritt policy list --status active

Test with dry-run

Use the dry-run flag to see which policies match without recording an evaluation:

bash
meritt intent evaluate --dry-run \
  --actor svc_data-pipeline \
  --action execute \
  --resource "model:gpt-4/inference"

Policy changes not taking effect#

Symptoms: You updated a policy but evaluations still use the old rules.

Likely causes:

  • The updated policy is still in draft status
  • Policy cache has not refreshed yet

Resolution: Ensure the policy status is active. Policy updates create a new version — verify the latest version is active with meritt policy get <policy_id> --show-versions. The policy cache refreshes within 30 seconds by default.

Token Issues#

Decision token rejected at enforcement#

Symptoms: The enforcement point rejects a valid-looking decision token with token_invalid or token_expired.

Likely causes:

  • The token TTL has expired (default: 5 minutes)
  • Clock skew between the token service and the enforcement point exceeds tolerance
  • The signing key has been rotated since the token was issued

Resolution:

Check token expiry

Decode the token to check its expires_at timestamp:

bash
meritt token inspect <token>

If the token has expired, submit a new intent to get a fresh token.

Verify clock synchronization

Ensure all services are synchronized via NTP. Intended tolerates up to 30 seconds of clock skew by default. Skew beyond this threshold causes valid tokens to be rejected.

Token scopes insufficient#

Symptoms: The enforcement point rejects a token with scope_insufficient.

Likely causes:

  • The evaluated policy grants narrower scopes than the enforcement point requires
  • The requested action does not match the scopes encoded in the token

Resolution: Review the policy rules to ensure they grant scopes that cover the action being enforced. Use meritt token inspect <token> to see the granted scopes, then compare against the enforcement point's required scopes.

Deployment Issues#

Health check failing after deployment#

Symptoms: meritt health --all reports one or more services as unhealthy after a new deployment.

Likely causes:

  • The service has not finished starting up
  • A dependency (database, cache, signing key) is not accessible
  • Configuration mismatch between the deployment and the expected environment

Resolution:

Wait for startup

Services may take up to 30 seconds to become healthy after deployment. Re-run the health check after waiting.

Check sub-checks

Query the individual health endpoint for the failing service and examine the checks object:

bash
curl https://api.intended.so/health

Look for fail entries in the checks object to identify the specific dependency.

Review logs

Check the service logs for startup errors:

bash
meritt ops logs --service policy-engine --since 5m

Circuit breaker tripped in production#

Symptoms: All intents are denied with "reason": "fail_closed" and "detail": "circuit_breaker_open".

Likely causes:

  • A downstream service exceeded its failure threshold
  • Network partition between Intended services

Resolution: Check the circuit breaker status with meritt ops circuit-breaker status. Identify the tripped breaker and investigate the underlying service failure. The circuit breaker will automatically probe and recover once the service is healthy. See Fail-Closed Controls for details.

Readiness check failing#

Symptoms: meritt ops readiness-check reports one or more failures.

Likely causes:

  • Incomplete configuration (missing policies, credentials, or network access)
  • A service dependency is down

Resolution: Follow the specific failure message from the readiness check output. Each check reports what it expected and what it found. See Operational Readiness for the full checklist.

Getting More Help#

If the steps above do not resolve your issue:

  1. Collect diagnostic output: meritt ops diagnostics --output diagnostics.json
  2. Check the Audit API for relevant events around the time of the issue
  3. Review the Glossary to ensure you are using the correct terminology in your queries
  4. Contact support with your diagnostic output and tenant ID