permission-core

    • Troubleshooting

    Start from structured error code and details.kind, then narrow the problem to initialization, subject identity, rule state, data guard, menu state, cache, or Vext route integration.

    Minimal Diagnostic Order

    Check health, direct roles, and an explanation before changing state. These reads identify the failing layer without accidentally granting new permissions in diagnostic code.

    const health = await pc.health();
if (health.status !== 'up') {
  logger.warn({ health }, 'permission core is not fully healthy');
}

const scoped = pc.scope({ tenantId: 'acme' });
const directRoles = await scoped.userRoles.getDirect('u-1');
const subject = pc.forSubject({
  userId: 'u-1', scope: { tenantId: 'acme' },
});
const explanation = await subject.explain('invoke', 'api:GET:/api/orders');

    Find by Symptom

    SymptomCheck firstUsually jump to
    can() returns false even though you expected allowreason/evaluations from subject.explain()Scope, Identity, and Decisions
    assert() throws PERMISSION_DENIEDexplain() with the same action/resourceScope, Identity, and Decisions
    Menu is visible but an action is disabledreason from subject.menus.getActionMap() and the load state from getViewState()Data, Menus, and Concurrency
    Menu config is saved but the role lacks permissionWhether role-menu preview includes the expected views/actions/responseFieldsData, Menus, and Concurrency
    Authorized collection returns no rowsscope, scopeFields, row where, and field permissionsData, Menus, and Concurrency
    preview or cursor is staleWhether input, scope, filter/sort, or state changedData, Menus, and Concurrency
    Vext route keeps returning 503Authentication context and route manifest changesCache and Vext Recovery

    Installation and Initialization

    Most startup failures come from a missing MonSQLize peer, an incompatible runtime, an unavailable database, or a schema contract mismatch. Treat these as readiness failures.

    Scope, Identity, and Decisions

    Subject scope must be complete and trusted. Missing policy context, no matching allow, explicit deny, disabled roles, or unavailable sources all fail closed.

    Data, Menus, and Concurrency

    Data filters, field projection, bulk writes, preview flows, menu availability, and revision conflicts all have explicit failure states. Refresh the current state instead of inventing revisions.

    Cache and Vext Recovery

    Cache incidents degrade health and should be recovered through the host MonSQLize cache backend. Vext routes without trusted authentication return authentication errors, and hot route manifest changes require restart.

    Continue with Production Operations.