Consul — service registration failed with ACL denial

Consul rejects service registration because the agent token lacks the service:write ACL permission, or the ACL system is enabled without a valid token.

intermediatedebuggingconsulacl

Symptoms

error: ACL not found or access denied
Service registration works with bootstrap token but not agent token
Consul UI shows the service but API registration fails

Possible causes

ACLs are enabled but the agent token does not have service:write permission
The token is expired or revoked
The ACL policy does not match the service name or namespace

Diagnosis steps

Check the agent token

consul acl token read -id $AGENT_TOKEN

Interpretation

Shows the policies attached to the token.

Test the policy

consul services register -token $TOKEN service.json

Interpretation

If denied, the policy does not grant the required permission.

Root cause

The Consul ACL system denies the registration because the token does not have service:write permission for the target service or namespace.

Fix

Create a policy with service:write for the service, attach it to the agent token, and retry the registration.

Verify the fix

Register the service with the updated token and confirm it appears in the catalog; verify an unauthorized token is still denied.

Symptom walkthrough

Consul rejects service registration because the agent token lacks the service:write ACL permission, or the ACL system is enabled without a valid token. The error appears in production but may not surface in local development because the conditions that trigger it depend on the deployment environment or runtime configuration. Understanding the full symptom set helps distinguish this issue from similar errors.

Diagnosis in practice

Follow the diagnosis steps in the frontmatter to isolate the cause. Each step includes a command and an interpretation of the output. The goal is to narrow down whether the issue is in the configuration, the runtime, or the application code. Reproduce the error in a minimal setup before applying a fix.

Root cause

The Consul ACL system denies the registration because the token does not have service:write permission for the target service or namespace.

Fix

Create a policy with service:write for the service, attach it to the agent token, and retry the registration. After applying the fix, monitor the system to confirm the error does not recur under load or in different environments.

Verification

Register the service with the updated token and confirm it appears in the catalog; verify an unauthorized token is still denied. If the verification passes, the fix is confirmed; if not, re-examine the diagnosis steps for missed contributing factors.

Diagnostic commands

Run these commands to reproduce and diagnose the issue:

consul acl token read -id $AGENT_TOKEN
consul services register -token $TOKEN service.json