nats-io/nats-server · error

Could not add shadow import subscription for account %q

Error message

Could not add shadow import subscription for account %q

What it means

Internal runtime error in account import processing: inserting the shadow subscription (the internal sub that realizes an account's imported subject) into the account sublist failed for account %q. Not a client input error — it signals an unexpected sublist Insert failure (e.g. invalid generated or duplicate subject) while wiring imports.

Source

Thrown at server/client.go:3340

		}
		subj := im.rtr.TransformSubject(s)

		nsub.subject = []byte(subj)
	} else if !im.usePub || (im.usePub && ime.overlapSubj != _EMPTY_) || !ime.dyn {
		if ime.overlapSubj != _EMPTY_ {
			nsub.subject = []byte(ime.overlapSubj)
		} else {
			nsub.subject = []byte(im.from)
		}
	}
	// Else use original subject

	c.Debugf("Creating import subscription on %q from account %q", nsub.subject, im.acc.Name)

	if err := im.acc.sl.Insert(&nsub); err != nil {
		errs := fmt.Sprintf("Could not add shadow import subscription for account %q", im.acc.Name)
		c.Debugf(errs)
		return nil, errors.New(errs)
	}

	// Update our route map here. But only if we are not a leaf node or a hub leafnode.
	if c.kind != LEAF || c.isHubLeafNode() {
		c.srv.updateRemoteSubscription(im.acc, &nsub, 1)
	} else if c.kind == LEAF {
		// Update all leafnodes that connect to this server. Note that we could have
		// used the updateLeafNodes() function since when it does invoke updateSmap()
		// this function already takes care of not sending to a spoke leafnode since
		// the `nsub` here is already from a spoke leafnode, but to be explicit, we
		// use this version that updates only leafnodes that connect to this server.
		im.acc.updateLeafNodesEx(&nsub, 1, true)
	}

	return &nsub, nil
}

// canSubscribeInternal determines if the client is authorized to subscribe to

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Inspect the account's imports for conflicting or overlapping subjects
2. Check server debug logs for the account name in the message to locate the failing import
3. Re-apply the account claim or import definitions if state is stale

When it happens

Trigger: Thrown at server/client.go:3340 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of nats-io/nats-server@3a66a489d2 (2026-09-02). Data as JSON: /api/errors/739d2b3050978e42. Report an issue: GitHub.