Error index

This page lists the messages Dox prints or throws, so you can search for the text you see.

• <...> is a part that changes, like a name or a number.
• Dart adds a prefix to some errors: Bad state: (StateError), Invalid argument(s): (ArgumentError), Unsupported operation: (UnsupportedError), Exception: (Exception).
• For problems that need a longer story, see Troubleshooting.

dox_core: start of the app

Text	When	What to do
APP_KEY is not set. Rundox key:generateand put the key in .env	appKey is empty. A StateError stops the app, unless APP_ENV is development, local, test or testing. Then it is only a warning.	Run dox key:generate, or set APP_KEY in the env.
APP_KEY must be exactly 32 characters. Rundox key:generate``	The key is shorter or longer. Same rule as above.	Run dox key:generate.
APP_KEY is a public sample key. Rundox key:generatefor a new one	The key is a known sample key. Same rule as above.	Run dox key:generate.
Unsupported operation: dox_http_native did not load: <reason>. Fix: ...	The native HTTP library is missing or from another version (native library ABI <x>, expected <y>). The app stops at start.	Do what the Fix: part says. See Troubleshooting.
Server started at http://<host>:<port> with <n> isolate (native)	Normal start. <host> is the address it listens on: [::] means all interfaces.	Nothing.
Windows: the native server runs on one isolate	Windows has no SO_REUSEPORT.	Nothing.
Socket.IO runs on <n> isolates: clients should use transports: ['websocket'] ...	Socket.IO with more than one isolate and long-polling on.	Use transports: ['websocket'] in the client.
[dox] isolate <n> error: <error>	An error killed a worker isolate. The stack is on the next line.	Fix the error. Dox restarts the isolate.
[dox] isolate <n> exited, restarting	A worker isolate died. A new one starts after 1 second.	Look at the error line above it.
SocketException: dox_http_native: bind failed (<code>) (OS Error: errno = <errno>), port = <port>	The port is in use.	See Troubleshooting.

dox_core: routes and controllers

These stop the app at start, so a bad route never reaches a request.

Text	When	What to do
Route <where>: the controller parameter type <T> is not known. Use DoxRequest, a @Dto class, an @Inject class, a @DoxModel, a type from Route.bind, or String, int, double, num, bool for path params. ...	A controller parameter has another type, the DTO is not in AppConfig.dtos, the class is not in the container, or there is no Route.bind<T> for a {param} of the route.	Change the type or add the binder. Run dart run build_runner build, and set dtos: dtos and container: registerContainer in AppConfig.
Route <where>: the action gives a function. Give it one controller parameter from the container, like (UserController c) => c.index. ...	A route action like (c) => c.index where Dox can not find the controller class.	Give the parameter its type, and mark the controller class with @Inject().
Bad state: <T> is not in the container. Add @Inject() above the class and rundart run build_runner build. ...	Dox needs a class that is not in the container.	Do what the text says, and set AppConfig(container: registerContainer).
Route name "<name>" is used twice: <method> <path> and <method> <path>.	Two routes have the same name.	Give one of them another name.
Invalid argument (name): No route has this name: "<name>"	route() or Route.url() with a name that no route has.	Check the name and the group name: prefix.
Invalid argument(s): Route "<name>" (<path>) needs the param "<param>".	route() without a value for a {param}.	Pass it in params:.
Invalid argument(s): Route "<name>" (<path>) has no param "<key>". ...	route() with a param the path does not have.	Remove it, or pass it in query:.
Bad state: No bound value of type <T> for the route param "<param>". ...	req.bound<T>() for a param with no Route.bind, or of another type.	Add Route.bind<T>('<param>', ...).
Route <where>: the controller has more path params than the route has {...} params (<n>).	The method asks for more path params than the path has.	Add the {param} to the path, or remove the parameter.
Route <where>: a controller can have one @Dto only.	Two DTO parameters.	Merge them into one DTO.
Route <where>: only positional parameters are supported, not named or [optional] ones (<type>).	Named or [optional] parameters.	Use positional parameters. Use int? with {id?} for an optional param.
Route <where>: a controller can not be generic.	The handler has type parameters.	Remove them.
Route <where>: can not read the controller type <type>.	Dox can not read the function type of the handler.	Use a plain method or function.

dox_core: env

Text	When	What to do
EnvException: the env is not valid then - <KEY> is missing	AppEnv.load() found a required key with no value.	Set the key, or give the getter a default.
- <KEY> must be <type>, not "<value>"	A value does not fit the getter type.	Fix the value. Check for a # comment after it.
Env key "<KEY>" is not set and has no default	Env.get<int>(), <num>, <double> or <bool> with no value and no default.	Set the key, or pass a default.
Env key "<KEY>" is not a valid <type>: "<value>"	Env.get<int>() (or another type) got text that is not that type.	Fix the value.

See Environment variables.

dox_core: requests (what the client gets)

An IHttpException with a text message answers {"code":"<errorCode>","message":"<text>"}. The table shows the message text.

Status	Message	When	What to do
404	<METHOD> <path> not found	No route matches.	Check the method, the path and the router prefix.
404	Not Found	A typed path param does not fit, like abc for int id, or a Route.bind finds no row.	Send a valid value.
400	The body is not valid JSON	A DTO reads a JSON body that does not parse.	Send valid JSON.
400	The form body is not valid	A urlencoded body that can not be decoded.	Fix the client encoding.
415	Unsupported Media Type	A DTO reads a body that is not JSON or form data.	Send Content-Type: application/json or form data.
413	Payload Too Large	The body is bigger than maxBodySize or maxMultipartSize.	Send less, or raise the limit.
419	CSRF token mismatch	CsrfMiddleware finds no CSRF token, or a wrong one, on a POST, PUT, PATCH or DELETE.	Send the token. See CSRF.
429	Too Many Requests	A RateLimit middleware sees too many requests. The Retry-After header says how many seconds to wait.	Wait, then try again. See Rate limiting.
422	{"_root":"The input has too many items (max 1000) or levels (max 10)"}	Form or query keys with more than 1000 list items or 10 levels.	Send less nested data.
422	{"<field>":"<message>"}	A DTO check failed.	See Validation rules.
431	(no text)	Native server: request line plus headers over 16 KB.	Send smaller headers or cookies.
500	Server Error, code server_error. When APP_ENV is development or local, the body is <error>.toString() as plain text.	Any error that is not an IHttpException. It also goes to the report method of the ExceptionHandler.	Look at the server log.

dox_core: DTOs, storage and config

Text	When	What to do
Bad state: This request has no session. Add SessionMiddleware() to globalMiddleware or to the route.	req.session on a route with no SessionMiddleware.	Do what the text says. See Session.
Bad state: <T> is not a known DTO. Add @Dto() to it, rundart run build_runner buildand setdtos: dtos(lib/generated/dtos.g.dart) in AppConfig.	req.validate<T>() can not find T.	Do what the text says.
Invalid argument(s): Storage disk "<name>" has unknown driver "<type>"	A disk in StorageConfig has a driver other than local, s3 or memory.	Fix the driver name.
Invalid argument(s): Storage disk "<name>" needs the "<setting>" setting. It is missing or empty.	An s3 disk without bucket, key or secret, on its first use.	Set AWS_BUCKET, AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.
Invalid argument(s): invalid file	Storage().put() with no extension:, and Dox can not find the type from the bytes.	Pass extension: 'pdf'.
403 invalid or expired signature	A Storage.route() URL without a valid signature, or after expires.	Make a new link with Storage().signedUrl().
404 file not found	Storage().stream() or download() of a missing file.	Check the path.
Invalid argument (trustedProxies): not an ip or cidr: "<value>"	A bad entry in AppConfig.trustedProxies.	Use an IP, a CIDR like 10.0.0.0/8, or *.
Invalid argument (type): must be asc or desc: "<value>"	orderBy(column, type) with another direction.	Use asc or desc.
400 decrypt_failed, The encrypted value is not valid	AESEncryptor.decode got changed text or a wrong key. It throws DecryptException. req.cookie() catches it and returns null.	Check the key. For a cookie, ask the user to log in again.

dox_auth

Text	When	What to do
401 Authentication failed	AuthMiddleware finds no token, a bad or expired token, or the user is deleted.	Send Authorization: Bearer <token>. Log in again.
Invalid argument(s) (password): The password is too long. bcrypt takes at most 72 bytes.	Hash.make() or Hash.makeAsync() with a password over 72 bytes.	Limit the length in the DTO. See Troubleshooting.
Invalid argument(s) (secret): The JWT secret is empty. Set APP_KEY (rundox key:generate).	JwtAuthDriver with an empty secret.	Set APP_KEY.
Invalid argument(s) (secret): The JWT secret is <n> bytes. It must be at least 32 bytes. ...	A short secret. In development, local, test and testing it is only a warning.	Run dox key:generate.

Hash.verify() gives false for a value that is not a bcrypt hash. It does not throw. Auth().attempt() returns null for a wrong password. It does not throw. See Authentication.

dox_orm

Text	When	What to do
Unsupported operation: dox_postgres_native did not load: <reason>. Dox needs it to talk to Postgres. Fix: ...	The native Postgres library did not load. The app stops.	Follow the fix in the message. See Postgres native.
Unsupported operation: dox_mysql_native did not load: <reason>. Dox needs it to talk to MySQL. Fix: ...	The native MySQL library did not load. The app stops.	Follow the fix in the message. See MySQL native.
PgServerException(<code>): <message>	The Postgres server said no, eg. code 23505 for a unique violation.	Read code, detail and constraint on the exception.
MysqlException(<code>, <sqlState>): <message>	An error from MySQL, eg. code 1062 for a duplicate key.	Read code and sqlState on the exception.
Exception: <name> not found	DatabaseConfig.connection (or withConnection()) names a connection that is not in connections.	Fix DB_CONNECTION or the map.
Exception: Invalid driver or not supported	A ConnectionConfig.driver Dox can not open.	Use Driver.postgres, Driver.mysql or Driver.sqlite.
Invalid argument(s): dox_postgres_native: bad connection config	The native driver can not read the connection values.	Check host, port, user, database.
Invalid argument(s): dox_mysql_native: bad connection config	Same, for MySQL.	Same.
SqliteException with unable to open database file	The SQLite folder does not exist.	See Troubleshooting.

dox_orm: schema builder

Text	When	What to do
Bad state: foreign key <name>: call on(table)	table.foreign('x').references('id') with no .on('table').	Add .on('table'), or use foreignId('x').constrained().
Unsupported operation: postgres: change() of an auto increment column is not supported	change() on an id() or increments() column.	Write the ALTER by hand with schema.driver.execute().
Unsupported operation: sqlite: can not add a primary key to an existing table	primary(...) in schema.table() on SQLite.	Make the table again with the key in schema.create().
Unsupported operation: sqlite: can not rebuild <table>, it has CHECK constraints	A SQLite rebuild (change(), foreign(), dropForeign()) on a table with other CHECKs.	Make the new table by hand in the migration.
Unsupported operation: sqlite: can not rebuild <table>, it has generated columns	Same, on a table with generated columns.	Same.
Bad state: sqlite: table <table> not found	A SQLite rebuild of a missing table.	Check the table name.
Bad state: sqlite: column <table>.<column> not found	change() or renameColumn() of a missing column on SQLite.	Check the column name.
Bad state: sqlite: foreign key <names> not found	dropForeign() of a key the table does not have.	Check the key name or columns.
Bad state: sqlite: rebuild of <table> breaks foreign keys	After the rebuild, rows point to missing parent rows.	Fix the data first.
Unsupported operation: sqlite: change() rebuilds the table, it only runs on a database	table.toSql(SqliteGrammar()) with change().	Run it on a database, not as text.

dox_migration

Text	When	What to do
Migration failed: <name> then the error	A migration threw, or the migrator can not reach the database.	Read the error below it. For a connection error, check DATABASE_URL or the DB_* values. A real env var wins over .env.
Unknown migration command: <cmd> (use run, rollback, reset, refresh, fresh or status)	dart run bin/migrate.dart <cmd> with another command.	Use one of the six.
Invalid argument(s): Invalid option <x>, use --step=<count>	rollback with a bad option.	Use --step=2.
Bad state: Migration <name> is both a Dart and a .sql migration	Two files with the same name in db/migration.	Rename or delete one.
Bad state: foreign key check failed: <table> points to a missing <parent> row	SQLite: a migration left a broken foreign key.	Fix the data in the migration.
Migrating: <name> / Migrated: <name>	Normal progress.	Nothing.
Migrations are already up to date!	Nothing to run.	Nothing.
Nothing to rollback!	No batch to undo.	Nothing.
No migrations found.	status with no migrations.	Check db/migration.
Bad state: Seeder <name> not found. Seeders: <names>	dox db:seed --class=<name> with a seeder that is not in db/seeders/seeders.dart.	Check the name, or add the seeder to the list.
Invalid argument(s): Unknown option <x>, use --class=<name>	dox db:seed with another option.	Use --class=UserSeeder.

See Migration.

dox_cache

Text	When	What to do
Invalid argument(s): Cache store "<name>" is not configured	Cache().store('<name>') or defaultStore names a missing store.	Add the store to CacheConfig.stores, or fix CACHE_STORE.
Invalid argument(s): Cache driver "<driver>" of store "<name>" is not supported	A store has a driver other than file, memory, redis or null.	Fix the driver name.
Unsupported operation: <Driver> does not support locks	lock() on the file or null store.	Use the memory or redis store.
Bad state: Cache value of "<key>" is not an integer	increment() or decrement() on a value that is not an int.	Store an int, or forget() the key.
Invalid argument(s): Cache value of "<key>" is bigger than <limit> bytes	A Redis value is too big.	Store less, or use files or a database.
Bad state: RedisDriver.flush needs a prefix. It will not delete the whole database.	flush() on a Redis store with an empty prefix.	Set a prefix.

See Cache.

dox_storage

The text has the form <Exception>: <message> (key: "<key>").

Text	When	What to do
FileNotFoundException: File not found	The file is not on the disk.	Check the path. Storage() paths start with /, Disk keys do not.
PermissionDeniedException: Permission denied	The OS (local) or S3 (403) refused it.	Check file rights, or the S3 key and bucket policy.
InvalidKeyException: Invalid key: path traversal is not allowed	A key with ...	Do not build keys from user input.
InvalidKeyException: Invalid key: absolute paths are not allowed	A Disk key that starts with / or a drive letter.	Remove the first /.
InvalidKeyException: Invalid key: key is empty	An empty key.	Pass a file name.
UnsupportedOperationException: urlBase and appKey are needed for signed URLs	signedUrl() on a local disk with no url, or no APP_KEY.	Set both.
UnsupportedOperationException: S3 signed URLs must expire within 1 second and 7 days	signedUrl() on S3 with a bad expiresIn.	Use a time up to 7 days.
UnsupportedOperationException: Disk "<name>" is not registered	Storage().disk('<name>') with a missing disk.	Add the disk to StorageConfig.disks.
DriverException: <S3 error>	Any other S3 error (network, 500, wrong bucket).	Read the S3 code in the text.

See File storage.

dox_validation

Text	When	What to do
Bad state: Schema has async rules. Use parseAsync() instead.	schema.parse() on a schema with an async rule.	Use await schema.parseAsync().
Bad state: Rule "<name>" is async. Use parseAsync() instead.	Same, for one AsyncRule.	Same.
Bad state: This refine is async. Use parseAsync() instead.	refine() with an async function and sync parse.	Same.
Bad state: DTO <name> has an async validate(). Use parseAsync() instead.	A DTO with Future<void> validate() checked with a sync call.	Use the async call, like req.validate<T>().
Bad state: No value: the key was missing. Check isPresent.	maybe.value on a Maybe<T> that is missing.	Check isPresent first.

See dox_validation.

dox_builder (build_runner)

These stop dart run build_runner build.

Text	When	What to do
The @Dto class <Name> has problems: then a - ... list	One or more lines below.	Fix each line.
- The field <Class.field> must be final.	A DTO field is not final.	Add final.
- The field <Class.field> must be athis.parameter of the unnamed constructor.	The field is not set by the constructor.	Add this.<field> to the constructor.
- A @Dto class needs an unnamed constructor.	Only named constructors.	Add const Name({...}).
- A @Dto class can not extend another class (<Parent>).	The DTO extends a class.	Copy the fields in.
- A @Dto class can not be generic.	The DTO has type parameters.	Remove them.
- The type <T> of <where> is not supported. Use a basic type, an enum, DateTime, RequestFile, a @Dto class, or a List or Map of them.	Field type not supported.	Change the type.
- @<Rule> does not fit the type <T> of <where>.	A rule on the wrong type, like @Email() on an int.	Move the rule, or change the type.
- @Length on <where> needs min:, max: or both.	@Length() with no limit.	Add min: or max:.
- The @Regex on <where> is not a valid regex: <reason>	The pattern does not compile.	Fix the pattern.
- @<Rule> on <where> needs a size like '2MB' (units B, KB, MB, GB), not "<text>".	Bad size text on @MaxSize or @MinSize.	Use '2MB'.
- @Dimensions on <where> needs at least one limit, like minWidth:.	@Dimensions() with no limit.	Add a limit, like minWidth: 100.
- The Maybe field <where> needs the defaultconst Maybe.missing().	A Maybe<T> field without that default.	Add it.
- <where> can not have both @Lowercase and @Uppercase.	Both on one field.	Keep one.
- The validate method of <Name> must take one DtoErrors:void validate(DtoErrors errors).	Wrong validate signature.	Use that signature.
Two @Dto classes are named <Name>: in <a> and <b>. Dox finds DTOs by name, so rename one.	Two DTOs with the same class name.	Rename one.
Env getter "<name>" has type <T>. Use String, int, double, num, bool, Uri, Duration, an enum or List<String>.	A @DoxEnv getter with another type.	Change the type.
@DoxModel can only be used on a class. / @DoxEnv can only be used on a class.	The annotation is on something else.	Put it on a class.
Conflicting outputs were detected ...	build_runner cache is out of date.	See Troubleshooting.

Native libraries (build hooks)

Printed during dart pub get, dox serve or dox build. <pkg> is dox_http_native, dox_postgres_native or dox_mysql_native.

There is no fallback. When a library is missing, the app stops with the reason and the fix. dox_http_native stops at start. The database drivers stop when the ORM opens the database.

Text	When	What to do
<pkg>: no native library for <os>-<arch>.	No ready build for this OS and CPU.	Install Rust.
<pkg>: download <file>: <status> / <pkg>: download <file> failed: <error>	The GitHub download failed.	Check the network, then dart pub get again.
<pkg>: sha256 of <file> does not match	The downloaded file is not the expected one.	Delete .dart_tool and try again.
<pkg>: cargo build failed	The build from source failed.	Read the cargo output below it.
Bad state: <pkg>: <path> does not exist	The lib_path user define points to a missing file.	Fix the path in pubspec.yaml.
<pkg> did not load: the native library is not in the build (...).	The app opens Postgres or MySQL, but pubspec.yaml skips that driver.	Remove its skip line. See Skip unused drivers.
Unsupported operation: dox_http_native can not detach the socket. Use NativeWebSocket.upgrade for a WebSocket.	Code called detachSocket() on a response. Rust owns the socket.	For a WebSocket use NativeWebSocket.upgrade(request).

See Native server.

dox_socketio

Printed to stderr. The connection or the request fails, the app keeps running.

Text	When	What to do
dox_socketio: handler error: <error>	Your namespace handler threw. The stack follows.	Fix the handler.
dox_socketio: request error: <error>	A Socket.IO HTTP request failed. The client gets 500.	Check the client version and transport.
dox_socketio: publish failed: <error>	The Redis or isolate adapter could not publish.	Redis adapter: check Redis. Isolate adapter: it should not happen, so report it as a bug.
dox_socketio: bad adapter message: <error>	The Redis or isolate adapter got a message it can not read.	Check that every app on the channel runs the same version.

CLI

Text	When	What to do
Could not find a command. Rundox helpfor more information.	dox with no command.	Run dox help.
Could not find a command named "<name>". Rundox helpfor more information.	Unknown command. A second line tells you about the dox: commands: key.	Check the spelling. For a package command, run dart pub get after you add the package.
More than one command is named "<name>", in: <packages>. ...	Two commands (in two packages, or twice in one) have the same name. Exit code 1.	Remove one of these packages, or ask its author to rename the command.
Skip <package>:dox: commands: must be a library of the package itself, like package:<package>/commands.dart.	The dox: commands: value is not package:<package>/<path>.dart, or has .., quotes or other characters. The other packages still work.	Fix the value in that package's pubspec.yaml.
Skip <package>:dox: commands:must be a library, like package:<package>/commands.dart.	The value is not a string (like a list).	Use one library.
Skip <package>: <library> is not there (<path>).	The commands library file is missing. The other packages still work. dox looks again on the next run.	Make the file, or fix the key.
Skip <package>: its pubspec.yaml is not valid YAML.	The package's pubspec.yaml can not be read.	Fix the YAML.
Could not load the package commands: ...	dox help could not run .dart_tool/dox/commands.dart (like a compile error in a commands library). The built-in commands are still listed.	Fix the error it shows.
bin/migrate.dart created.	make:migration, or a migration:* command, made the missing entry file.	Nothing.
Invalid number of arguments for command "<name>".	Too few or too many arguments.	Run dox help <name>.
Command "<name>" not found.	dox help <name> with an unknown command.	Run dox help.
<name> already exists	A make:* file is already there.	Pick another name, or delete the file.
Folder name "<name>" already exist	dox create into a folder that exists.	Pick another name.
Invalid option <x>, use -m or --migration	dox make:model with another option.	Use -m.
Invalid option <x>, use --step=<count>	dox migration:rollback with another option.	Use --step=2.
Skip <file>: no class that extends Migration.	A Dart file in db/migration has no migration class.	Add class X extends Migration, or move the file.
.env.example is missing.	dox env:generate with no example file.	Make .env.example.
lib/config/env.dart is already there. Delete it to make it again.	dox env:generate again.	Delete the file, or edit it by hand.
lib/config/env.dart is missing. Rundox env:generatefirst.	dox env:check with no env class.	Run dox env:generate.
pubspec.yaml has no name.	dox env:check can not find the package name.	Add name: to pubspec.yaml.
bin/openapi.dart is missing. Make it with: ...	dox openapi:generate with no entry file.	Make bin/openapi.dart. See OpenAPI.
zsh: command not found: dox	$HOME/.pub-cache/bin is not in PATH.	See Troubleshooting.

See CLI.