Troubleshooting

Most console.warn/console.error lines below are literal strings logged by @gentleduck/iam - search for the text between the brackets and the tag tells you which subsystem produced it. Thrown errors are IamErrors: search for the CODE shown instead, and read the detail off err.meta, since err.message is the bare code.

Start here

Pick your branch from the tag in the message, or from the fact that nothing was thrown at all.

The two branches under "Did something throw?" behave differently. A throw is a configuration or input problem and is always reproducible from a unit test; the tag in the message routes you to the right table below. A wrong decision with no throw is a policy problem, and the only reliable instrument is explain() - which is why the "mode development?" node exists: production mode never builds a trace, so a production-only bug has to be reproduced on a dev-mode replica before you can see targetMatch, conditionsMet, or the conditions array.

Diagnostic toolbox

Start with explain(). Nine times out of ten the trace names the rule and the failed condition outright.

Engine configuration and startup

Roles and policies rejected at build time

Runtime denials and throws

Adapters and transports

Framework and client integration

The check is wrong but nothing threw

No error message means the engine did exactly what your policies said. Work the trace.

const trace = await engine.explain('user-bob', 'update', {
  type: 'post',
  id: 'post-1',
  attributes: { ownerId: 'user-bob' },
})

console.dir(trace, { depth: null })

Read trace.policies in order:

The three conditions that fail most often:

• Strict equality. eq is === with no coercion. subject.id of '42' against resource.attributes.ownerId of 42 is false. So is 'Admin' against 'admin'.
• Numeric-only comparison. gt, gte, lt, lte return false unless both operands are numbers. An ISO-8601 date compared with gte never matches. Use before / after, which coerce to epoch milliseconds.
• A missing attribute. resolve() returns null for a path that does not exist, and only exists treats null specially. If the resource was passed as { type: 'post', attributes: {} }, every resource.attributes.* condition is comparing against null.

Checks are slower than expected

engine.stats.get() returns { hits, misses, size } for each of the five caches - policies, roles, rbacPolicy, mergedPolicies, subjects. There is no error counter; use healthCheck().lastError and the onError hook for that.

• High subjects miss rate - only the subject cache is bounded by maxCacheSize (default 1000). If you have more active subjects than that, raise it.
• High miss rate everywhere - cacheTTL (default 60 seconds, not milliseconds) is too short, or an invalidator is flushing more than it needs to.
• size at zero after a while - something is calling engine.cache.invalidate() or publishing broad invalidation events. Check the invalidator channel.
• Good hit rates but still slow - you are in mode: 'development', which allocates a full decision object per check. Production mode is roughly 7x faster. See modes and benchmarks.
• A UI permission map dominating the profile - pass { telemetry: false } to engine.permissions() to skip per-check onMetrics.

Cold-start latency is a separate problem: call await engine.preload() at boot so the first real request does not pay the adapter round trip.

Getting help

• Run engine.explain() and include the trace in the report.
• Include engine.healthCheck() output and the engine's mode, policyCombine, and defaultEffect.
• File issues at github.com/gentleeduck/gentleduck/issues.

See also

• Cookbook - the working shapes of the recipes that go wrong here
• Production hardening - the configuration most of these errors are about
• Validation - the full issue-code reference
• Explain - the trace structure in detail