setDebug

Turns the sensitive debug channel on or off for the whole process: the raw data nautilus redacts everywhere else, for diagnosing a failure the redacted error does not explain. See the debugging guide for what each tier prints and how to share its output safely.

Usage

import { Nautilus } from '@deltadao/nautilus'
 
Nautilus.setDebug({ level: 'sensitive' }) 

Without a code change, in Node: NAUTILUS_DEBUG=sensitive node app.js. See environment variables.

Returns

void

Parameters

options

• Type: DebugOptions

Replaces the whole setting (options left out go back to their defaults) and overrides the environment variables. An unknown level or topic throws a TypeError.

level

• Type: 'off' | 'sensitive' | 'secrets'

sensitive hides long-lived credentials best effort, by name and shape (see the debugging guide): scan its output before sharing it.

The signer's private key or mnemonic is never printed, at any tier: nautilus never holds them, the signer does.

topics

• Type: DebugTopic[], of 'node' | 'wallet' | 'policy' | 'rpc' | 'order' | 'nonce' | 'store' | 'compute'
• Default: all

Only events about these topics print. Every topic also carries the raw fields of nautilus's own log events of its component, but only of events printed at the current log level: pair the channel with NAUTILUS_LOG_LEVEL=debug (or configureLogging({ level: 'debug' })) to see them all. The raw error of an operation's …operation.failed (or …query.failed) event goes to the topic of where the error came from when nautilus knows it: a PolicyDeniedError or CredentialPresentationError to policy, a WaltIdWalletError to wallet, a NonceGuardError or IndexerNonceStuckError to nonce, also as the cause of another error. Any other error goes to the operation's topic (access.operation.failed to order, publish.operation.failed to rpc).

sink

• Type: (event: DebugEvent) => void

Receives each event instead of stderr, e.g. to write a local file. A sink that throws is ignored.

Nautilus.setDebug({
  level: 'sensitive',
  topics: ['policy', 'wallet'],
  sink: (event) =>
    appendFileSync('nautilus-debug.jsonl', `${JSON.stringify(event)}\n`, { mode: 0o600 }) 
})

Each event is a DebugEvent:

Output

Without a sink, each event is one line on stderr (console.info in a browser), prefixed with its tier and topic, and within an operation its name and opId after the time (… 2026-10-10T13:36:58.772Z [access 3f9a2c1b07e4] verifier per-policy results …). Line breaks and control characters in the data are written as JSON escapes, so an event never spans two lines:

[nautilus:debug:sensitive] [policy] 2026-10-10T13:36:58.772Z [access 3f9a2c1b07e4] verifier per-policy results (checkSessionId) {"sessionId":"…","verificationResult":false,"policies":["VerifiablePresentation holder-binding: failed (java.lang.NullPointerException)", …]}
[nautilus:debug:SECRETS] [rpc] 2026-10-10T13:37:02.104Z [publish 8c41d07e5a19] log event publish.metadata.events_unchecked before redaction {…}

What does not change

Errors, return values (e.g. PublishResponse.stored), PolicyDeniedError and log events stay exactly as redacted as with the channel off. Apps log, store and return those, so nautilus never un-redacts them; the raw values go to this channel only.

Nothing in what nautilus sends changes either. After a presentation the verifier refused, nautilus reads the verifier's record (checkSessionId) with the channel on or off, to name the failed policies in the PolicyDeniedError; with the policy topic on, the whole record also reaches the channel.

Warning on enabling

Turning a tier on prints a warning on stderr that no log level or sink suppresses, once per tier per process. Under NODE_ENV=production it is stronger and says how to turn it off.

Environment variables

Read once, when nautilus is imported. setDebug overrides them. In a browser there is no environment; use setDebug.

Case does not matter. Only the tier names count: NAUTILUS_DEBUG=1 or true turns nothing on, so secrets is reached only by naming it, and NAUTILUS_DEBUG_TOPICS alone turns nothing on. An unknown value is ignored, and a config.env.invalid warning says so. An unknown topic is dropped from the list; a list with no known topic turns on no topic, never all of them.

NAUTILUS_DEBUG=sensitive NAUTILUS_DEBUG_TOPICS=policy,wallet node download.js 2> debug.log