Prefer it still? Press here
Match log lines and errors with their fixes, and separate command, worker, connection and request problems
Start with what the bot printed. The client logs startup, readiness, lost connections, rate-limit waits, shutdown and every application error by default. Each readable log line shows its record code in brackets after the category, such as [lifecycle. Then check the operation's Result or native Effect error. The describe function prints any SDK error with its code, suggested fix and cause chain
The error and log codes page lists every code with its meaning and fix. The table below covers the most common ones
configuration.invalid with field token#The token was missing or empty, or it started with Bot or Bearer
The environment variable holding the token is probably unset. Start the bot with node --env-file=.env bot.js from the folder that holds .env, or set the variable in the shell, and pass only the token without a scheme. Surrounding spaces and one pair of quotes are removed. In a project made by fluxerly init, set FLUXER_ in the .env file that init wrote
configuration.invalid for an unknown option#An option name is misspelled or not supported where it was passed
The hint names the closest supported option, as in Did you mean "logging"?, then lists every supported one
lifecycle.connectionEnded with close 4004#Fluxer rejected the bot token
Check that the configured value is the whole bot token, or regenerate the token in the application settings and update the configuration. The SDK does not retry a rejected token
lifecycle.connectionEnded with close 4011 or 4010#The gateway requires more shards, or rejected the shard assignment
Set sharding: "auto" for a bot in one process, or configure sharding with the total shard count the gateway expects. See sharding
lifecycle.resharded #Fluxer closed a shard with 4011 under sharding: "auto" or without sharding settings, so the SDK counted the communities again and moved every shard to a larger plan. Events sent during the move were missed
Nothing, unless it repeats. Without sharding settings, set sharding: "auto" so the next start opens enough shards at once. After 3 moves within an hour, the next 4011 ends the client with lifecycle
supervisor.resharded #A child's shard was closed with 4011 under the supervisor's total. At Warn, the supervisor stopped every child, counted again and started a larger plan. At Error, it had already moved 3 times within an hour or reached 16,384 shards, so it shut down
At Error, check why the community count keeps growing, or choose a larger numeric total
lifecycle.connected #Every shard is connected. The message names the bot and how many communities it is in. At Warn, the bot is not in any community
At Warn, open the installation link in the message and add the bot to a community. See Create a bot
lifecycle.retry #A startup connection attempt failed and the SDK is trying again
Nothing, unless startup then fails. The message names the reason and the delay
lifecycle.connectionLost #A connection dropped and the SDK is reconnecting
Nothing, unless it repeats. The message names the close code, its meaning and whether the session resumes
lifecycle.sessionReset #The session could not resume, so the next connection starts a new one
Events sent while disconnected are not replayed. Refresh state that matters
lifecycle.cacheRefill #Shards resumed sessions from the session store, which carry no community data, so the SDK refilled the enabled community, role and channel caches through REST. At Warn, some communities failed or the refill stopped early, such as when the community list repeated a page
At Warn, read the message and any error. The missing cache entries fill as events and requests arrive
lifecycle.draining , lifecycle.drained #A shutdown with drain stopped accepting new events and waited for running handlers, their waiting events, running scheduled tasks and REST requests. A lifecycle record means all of it finished in time
Nothing
lifecycle.drainTimedOut #The drain time ran out, so shutdown cancelled the work that had not finished. The fields name how many handlers, events, tasks and requests
Make handlers and tasks finish sooner, or raise drain if the process may take longer to stop
events.discarded #A subscription stopped with events still waiting in its queue, so they never reached it. At Info the client was closing, and at Debug the subscription itself closed. The count is in fields, and diagnostics() includes it
At Info, shut down with drain to let waiting handler events run first
events.refused #A draining shutdown received events that open subscriptions or collectors would have received and did not deliver them, because it accepts no new events. The count is in fields, and diagnostics() includes it
Nothing
rest.busy #A request failed with reason busy because the REST queue or the upload byte budget was full. It is logged at most once a minute, and every such failure is counted in diagnostics()
Send fewer requests at once, or raise the limit the message names
rest.rejected #The SDK logs HTTP 401 or 403 rejections at Warn even when the application handles the Result, because they usually indicate a lasting token or permission problem. It holds the Warn for up to one second, replacing it with the handler or command's failure record only if that callback fails with the same rejection while it is held and no on hook is configured for that failure. Identical repeats collapse into one record per minute by default
Follow the record's hint. A bot that expects these rejections can set the rest category to error, as logging shows
ratelimit.wait #A request waited for Fluxer's rate limit
Spread out bursts on the named route. Waits under one second are logged at Debug
ratelimit.deadline #A rate limit's required wait would pass the request deadline, so the request failed without waiting
Raise the operation's timeout, or retry after the wait named in the record
events.handlerFailed #Fix the error shown with its stack. The handler keeps receiving later events. When an on hook exists but did not receive the report, fields says why: queue, interrupted, client or subscription
events.dropped #A subscription queue was full, so an event was dropped. By default the oldest waiting event is dropped
Handle events faster, raise max or concurrency, or accept the drops
events.overflow #A subscription registered with the opt-in overflow stop ended because its queue was full
Keep the default drop, or observe wait and register again
events.hookFailed #The on hook itself threw
Fix the hook. The original failure is logged right after it
events.registeredAfterShutdown #A handler, subscription or command router was registered after shutdown began, often from a handler still running at the time. It received an already-closed handle and never runs
Nothing during shutdown. At other times, register everything before stopping the client
gateway.ignoredEventRegistered #A handler is registered for an event whose dispatch types are all listed in gateway
Remove those types from gateway, or remove the handler. See configuration
gateway.dispatchRejected #Fluxer sent an event the SDK could not validate, so it was skipped
Update the SDK. The record names the event type and failing field. Cached entries it could affect were cleared
commands.rejected and commands.unmatched (Debug)#A command guard, cooldown or argument rejected a message, or no command matched
With run, argument errors, active cooldowns and guards with a deny reason get a reply unless on is "silent". A guard returning false sends nothing, even with the reply default. Add on to a router from commands, and on where users need feedback for unknown commands, a group without a subcommand or a syntax mistake such as an unclosed quote
SdkDefect with code sdk.defect #An unexpected SDK or cleanup fault
Report it with the output of describe. Code application instead points at application code: The callback named in its cause, or a property getter on passed options or input that threw the cause
Run with FLUXERLY_ to add Debug records for every area, or FLUXERLY_ for selected ones. See logging
A messages or messages call made after shutdown began returns a collector whose result fails with Client, as for a collector that was already running when shutdown started. Registering middleware with client on a closing client still throws Client in the default API, or dies with it in the Effect API. Invalid arguments remain misuse and throw Configuration whatever the client state
node: .env: not foundNode.js could not open the file named after --env-file. Run the command from the bot's folder, and check that the file is named exactly .env. Some editors, such as Notepad, save it as .env.txt. Show file extensions in the file manager to spot that
Error: Fluxerly needs Node.js 24.15 or newer, but this is Node.js 22.12.0. Install a current Node.js release from https://nodejs.org, then run the bot againThe SDK checks the Node.js version when it loads. Run node --version to see the version in use, install a newer release, and open a new terminal so that it is found first
Error: Fluxerly is ESM-only. Use import, and set "type": "module" in package.json (or use .mjs files)The SDK ships only ECMAScript modules. Replace require( with import, and either add "type": "module" to the project's package.json or name the file with .mjs
Install the Node.js types as a development dependency and include them, for example with "types": ["node"] in tsconfig.json. Handler signals are Abort values and clients support await using, so the SDK's declarations use those Node.js types
npm install --save-dev @types/nodepnpm add --save-dev @types/nodebun add --dev @types/nodeCheck these in order:
!ping command, with command names matched without regard to letter caseregister or registerMany call. Each call returns a new router, so attaching an earlier one misses later commandsdiagnostics().counters . With runBot , argument errors, active cooldowns and guards with a deny reason get an explanation unless onReject is "silent". A guard returning false intentionally sends nothing. A router from commands.create sends these explanations only with onReject: "reply" , and onUnmatched answers unknown commands, a group typed without a subcommand and a syntax mistake such as an unclosed quotecommands.failed with a message that tells local validation, provider rejection, timeout and delivery uncertainty apartA callback that returns an Err result fails like one that throws, so its error reaches on or the log. Handle an expected failure inside the callback when it should not count as a failure. See commands and failure handling
A webhook or OAuth call can fail because Fluxer rejected a credential other than the bot token. The hint of the Webhook or OAuth then names the credential the request sent:
Suppose a kick, ban, timeout, role change or deletion of another person's message fails with HTTP 400 and errors returns "two, although the bot holds the permission. The community requires two-factor authentication for moderation, and the account that owns the bot's application does not have it enabled. The community's mfa is Guild in such a community
Enable two-factor authentication on the account that owns the bot's application, then try again. Retrying without that change fails the same way. See communities that require two-factor authentication
Look for events records and diagnostics(), which show that events exceeded a handler's queue limits. A handler or middleware failure, including a synchronous throw, releases its handler slot and partition key without stopping the subscription. A full queue drops the oldest waiting event instead of stopping, or for a partitioned handler the oldest event of the longest backlog. diagnostics() shows which events were dropped
A client subscription registered with overflow: "stop" closes when its queue is full, while the gateway stays connected. Observe its wait outcome. The SDK runner watches its event subscriptions, its command router and the client connection. The diagnostics() counters show registrations and running callbacks, but cannot tell whether a particular application task is working
Enable Debug records for REST with logging: { categories: { rest: "debug", ratelimit: "debug" } } or FLUXERLY_. Each request prints its method, route template, status, duration and attempt, and each rate-limit wait prints its route and delay. Retries and waits are also counted in diagnostics()
The diagnostics() and active values show local queueing for this client. An operation deadline includes the wait in that queue and required SDK cleanup. A timeout after the request was sent does not prove that the write failed on Fluxer, so it is an uncertain write. Do not replay it blindly
Each lifecycle record names the reason and the next step, including the close code and its meaning when one is available. Transient recovery differs from terminal authentication or protocol rejection, which ends with lifecycle and the error shown in full. The retained run() or wait outcome supplies the terminal result
Do not create another client or repeat connect() merely because the existing client is recovering. The client already owns that recovery lifetime. A closed client requires a new explicitly owned instance
Check which work is still running. SDK shutdown waits for its own resources to close. It also waits for collector progress callbacks and native scoped finalizers, so one of those that never finishes can hold up shutdown. The lifecycle record reports how long cleanup took, and each failed cleanup step is logged as lifecycle
Handlers are different. A stop requested through the run signal or a process signal, or a call to client, lets running handlers, scheduled tasks and their REST requests finish for a limited time, logged as lifecycle, and then cancels what is left. A plain client cancels them at once. No shutdown waits for work a handler did not return, so database writes or detached Promises can finish after the subscription closes. Use explicit application tracking when that work must settle before exit
Avoid process as a cleanup shortcut. Set process after application cleanup instead. Neither cancellation nor a timeout proves rollback of an external mutation
Record the SDK version from the lifecycle record, the Node version, the record codes and the output of describe. The SDK masks tokens, Authorization headers, client secrets, invite codes and the user name and password in URLs in every record
Leave unsafe payload logging off when sharing logs. Application error messages and stacks still appear in ordinary logs, so redact message content from those errors too