NATS Account Added or Removed: What It Means and How to Fix It

An account added or removed event means the set of accounts on your NATS deployment changed between two consecutive monitoring epochs. An account either appeared (new account provisioned) or disappeared (account removed from configuration or JWT resolver). This check provides an audit trail for account lifecycle changes — the foundational isolation boundary in multi-tenant NATS deployments.

Why this matters

Accounts are the primary isolation mechanism in NATS. Each account defines a separate subject namespace, its own connection and subscription limits, and explicit import/export boundaries for cross-account communication. Adding an account creates a new tenant boundary. Removing one destroys it — and every client connection within that account is immediately terminated.

When an account is removed unexpectedly, the impact is immediate and disruptive. Every client authenticated against that account loses its connection. JetStream streams and consumers owned by the account become inaccessible. Cross-account imports that other accounts depend on stop working, breaking data flows for tenants that had nothing to do with the change. In a multi-tenant platform, removing the wrong account is equivalent to taking down an entire customer’s infrastructure.

Even intentional account changes need tracking. A new account added without proper limits can consume unbounded resources. An account removed without verifying that its exports are no longer imported elsewhere creates orphaned dependencies that fail silently. This check ensures every account lifecycle event is visible to operators, whether it was planned or not.

Common causes

• JWT push or revocation. In JWT-based deployments, accounts are managed via nsc and pushed to the server’s resolver. Adding a new account JWT or revoking an existing one changes the active account set. This is the normal provisioning workflow, but the check ensures visibility into every change.

• Configuration file update. In config-file-based deployments, accounts are defined directly in the server configuration. Adding or removing an accounts block entry and reloading the server changes the account set immediately.

• Operator key rotation. When an operator signing key is rotated, account JWTs signed with the old key may fail validation. The server drops accounts whose JWTs it can no longer verify, causing them to disappear from the active account set.

• Resolver cache expiration. With the full resolver, account JWTs are cached on disk. If the cache is cleared (disk replacement, container restart without persistent volume) and the account JWT is not re-pushed, the account disappears on the next server start.

• Automated tenant provisioning. CI/CD pipelines or tenant management systems that create and destroy accounts as part of their normal workflow. The check fires for each change, providing an audit log even when the changes are expected.

• Accidental deletion. An operator removes the wrong account from the configuration or revokes the wrong JWT. Without this check, the mistake may not be caught until affected clients start reporting connection failures.

How to diagnose

List current accounts

Check which accounts are currently active on the server:

nats server report accounts

This shows all accounts with their connection counts, subscription counts, and throughput. Compare with your expected account list.

Check for recently added accounts

For JWT-based deployments, list accounts in the operator store:

nsc list accounts

Compare this list with the accounts reported by the server. Any account in nsc but not on the server may have failed to push. Any account on the server but not in nsc may be from a stale cache.

Check for recently removed accounts

Review the server logs for account removal events:

grep -i "account" /var/log/nats/nats-server.log | grep -i "removed\|expired\|revoked"

Verify cross-account dependencies

If an account was removed, check whether other accounts imported from it:

nsc describe account <remaining-account> | grep -A5 "Imports"

Any import referencing the removed account’s exports will fail silently — the importing account’s subscribers on that subject will simply stop receiving messages.

Check connection impact

If the change was a removal, check for client disconnections that correlate with the epoch:

nats server report connections --sort in-msgs

A sudden drop in connections for the affected account confirms clients were disconnected when the account was removed.

How to fix it

Immediate: verify intent

Confirm the change was planned. Check your change management records, CI/CD pipeline logs, and operator activity. For JWT-based systems, check the nsc commit history:

cd ~/.local/share/nats/nsc/stores
git log --oneline -10

If the removal was accidental, restore the account immediately. For JWT-based deployments:

# Re-push the account JWT
nsc push -a <account-name>

For config-file deployments, restore the account block in the server configuration and reload:

nats-server --signal reload

Short-term: audit dependencies and limits

For newly added accounts, ensure proper limits are configured to prevent resource exhaustion:

1
// Go — connect and verify account info
2
nc, err := nats.Connect(url, nats.UserCredentials("new-account-user.creds"))
3
if err != nil {
4
    log.Fatal(err)
5
}
6

7
// Verify JetStream access
8
js, err := nc.JetStream()
9
if err != nil {
10
    log.Fatal(err)
11
}
12
info, _ := js.AccountInfo()
13
fmt.Printf("Storage: %d/%d bytes\n", info.Store, info.Limits.MaxStore)
14
fmt.Printf("Memory: %d/%d bytes\n", info.Memory, info.Limits.MaxMemory)

1
// TypeScript (nats.js)
2
import { connect } from "nats";
3

4
const nc = await connect({
5
  servers: "nats://localhost:4222",
6
  user: "new-account-user",
7
  pass: "password",
8
});
9

10
const jsm = await nc.jetstreamManager();
11
const info = await jsm.getAccountInfo();
12
console.log(`Streams: ${info.streams}/${info.limits.max_streams}`);
13
console.log(`Storage: ${info.store}/${info.limits.max_store}`);

For removed accounts, verify that no remaining accounts have broken imports:

# Check all accounts for orphaned imports
nsc list accounts | while read acct; do
  nsc describe account "$acct" 2>/dev/null | grep -q "Import" && echo "Check imports for: $acct"
done

Long-term: formalize account lifecycle

Implement account provisioning as code. Define all accounts in version-controlled configuration (Terraform, Helm values, nsc stores in Git). Every account change should go through code review before deployment.

Set up alerting on this check. While this is an informational check, unexpected account changes should trigger investigation. Configure your monitoring to alert on account additions or removals that don’t correlate with a known change window.

Maintain an account registry. Document each account’s purpose, owner, dependencies (imports/exports), and expected lifecycle. When this check fires, you can immediately determine whether the change is expected and who to contact if it’s not.

Frequently asked questions

What happens to client connections when an account is removed?

All client connections authenticated against the removed account are disconnected immediately. The server sends a -ERR and closes the connection. Clients with auto-reconnect enabled will attempt to reconnect, but authentication will fail because the account no longer exists. JetStream streams and consumers owned by the account become inaccessible.

Does adding an account require a server restart?

No. In JWT-based deployments, pushing a new account JWT via nsc push makes the account available immediately — no restart or reload needed. In config-file deployments, adding an account to the configuration file and sending a reload signal (nats-server --signal reload) activates the account without restarting.

How does this check handle the system account?

The system account ($SYS) is always present and is excluded from this check. Only user-defined accounts are tracked for additions and removals. Changes to the system account configuration are caught by other checks (e.g., Config Reload Detected).

Can I see which specific accounts were added or removed?

Yes. Synadia Insights reports the specific account names that appeared or disappeared between epochs, along with the server(s) where the change was observed. This gives you an immediate audit trail without needing to diff server state manually.

How do I prevent accidental account removal in production?

Use a GitOps workflow for account management. Store all account JWTs or configuration in version control, require code review for changes, and deploy through CI/CD pipelines. For JWT-based deployments, nsc stores can be committed to Git, giving you full history and the ability to revert any change.