Troubleshooting
Fix common setup errors. Each heading matches the anchor in Shardwire error messages (See: …#anchor).
When an error ends with See: https://shardwire.js.org/docs/troubleshooting#…, jump to the same anchor below. For types and error classes, see Reference → Errors & failures.
Official examples (env layout, expected logs): Getting started → Choose your path.
Start with capabilities
Most “nothing happens” issues are permissions and intents, not a broken network. Check app.capabilities() after connect and compare to what you subscribed to.
Node.js 22+ and WebSocket
App processes need Node.js 22+ so globalThis.WebSocket works (same as modern browsers). Upgrade Node; polyfilling WebSocket on older Node is not supported.
Vite and zlib-sync
Bundlers may pull discord.js (and optional zlib-sync) if you import from the shardwire root in a browser bundle.
Fix: import app-side code from shardwire/client only. Keep createBotBridge in Node-only bot files.
Vite and crypto
Use shardwire ≥ 2.0.0 on Node 22+; the client path uses globalThis.crypto for request IDs so Vite does not need node:crypto.
Browser: WebSocket is not a constructor
Use Node 22+ and a current shardwire so the client build does not ship the wrong ws shim into the browser.
Connection and authentication
The app could not open The Connection or the secret did not match. Check url (including path, often /shardwire), secret, and that the bot bridge is running.
App bridge is not connected
You called an action or API that requires an active session. await app.ready() first and avoid using app.actions after close().
Capability not available
The bridge did not expose that event or action for this app—usually intents, secret scope, or negotiation. Compare app.capabilities() to your subscriptions and manifest. See How it works and Bridge capability error.
Action request failed
The bridge rejected or could not complete an action request. Log result.error (or the thrown ActionRequestError) and check Action failure.
Action execution errors
Discord rejected the underlying operation (permissions, state, etc.). Inspect ActionExecutionError details and Action error.
Strict startup failed
ready({ strict: true }) found a mismatch between your manifest, bot intents, secret scope, and subscriptions. Use diagnoseShardwireApp and print formatShardwireDiagnosis for a human-readable report—see formatShardwireDiagnosis.
Strict mode needs a manifest
ready({ strict: true }) requires a manifest object. Pass defineShardwireApp(...) (or an equivalent manifest).
Unknown manifest event
defineShardwireApp listed an event name that is not in the Shardwire catalog. Use getShardwireCatalog() for valid names.
Unknown manifest action
defineShardwireApp listed an action name that is not in the catalog. Use getShardwireCatalog().
Filter references unknown event
filters in the manifest mention an event you did not declare in events.
Filters for an event not listed
You added filters for an event that is missing from events.
Unsupported filter key
A filter key is not valid for that event. Check app.catalog().subscriptionFilters.
Must be a positive number
A numeric option (for example idempotency TTL) must be a positive number.
Scope must be * or an array
Secret scope allow must be "*" or an array of permission strings.
Scope contains a non-string
Every entry in the allow array must be a string.
Unsupported scope value
A permission string is not recognized. Regenerate scope from generateSecretScope or copy from the catalog docs.
Secret must be non-empty
server.secrets entry must be a non-empty string (or an object with id and value fields when using object form).
Secret value required
When using object form, value must be non-empty.
Secret id required
When you supply an id, it must be a non-empty string.
Bot token required
createBotBridge needs token (your Discord bot token).
Bot intents required
Pass at least one Discord intent so the runtime knows what to subscribe to.
Idempotency scope invalid
server.idempotencyScope must be "connection" or "secret".
Secrets required
server.secrets must be a non-empty array.
Duplicate secret id
Two secrets share the same id. Use unique ids or omit ids where allowed.
Duplicate secret value
Two secrets share the same value. Each connection secret should be distinct unless you intend reuse.
App URL required
connectBotBridge needs url.
App URL invalid
url must parse as a valid URL.
App URL protocol
url must use ws:// or wss://.
Non-loopback requires wss
If the host is not loopback, use wss:// (TLS).
App secret required
connectBotBridge needs secret.
App secretId invalid
secretId must be a non-empty string when provided.
App name invalid
appName must be a non-empty string.