Refusals

When Luau Run will not do something, it prints a code and what to do next. Find the code on this page. A code ending in * covers every code that starts that way.

Exit codes says what each exit code means.

Settings

Code	What happened	What to do	Exit
command.manifest-invalid	luau-run.toml is not valid TOML.	Fix the line the message names.	64
command.field-unknown	luau-run.toml has a key Luau Run does not know.	Fix the name, or remove it.	64
test.field-unknown, test.roblox-studio-field-unknown	A setting under [test] or [test.roblox-studio] is not one Luau Run knows, usually a typo.	Fix the name. Project settings lists them.	64
test.worker-count-invalid	worker-count is not a whole number from 1 to 64.	Set it from 1 to 64.	64
test.rule-glob-invalid, test.runner-rule-glob-invalid	A rule’s glob is empty, starts with / or ./, or holds a backslash.	Write it from the project’s folder with forward slashes, such as tests/roblox/**.	64
test.jest-portable-surface-invalid	[test.jest-portable] is empty, or its surface is not full or test-globals.	Set surface, or leave the table out.	64
command.luau-run-too-old	The project’s luau-run-version names a newer Luau Run.	Run luau-run update.	64
command.tool-unknown	[tools] names something other than lute or jest-portable.	Remove it.	64
command.tool-version-unknown	[tools] lute names a version this Luau Run does not know.	Run luau-run pin lute <version>, or use a version the message lists.	64
command.tool-hash-mismatch	[tools.lute] gives other hashes than this Luau Run knows for that version.	Set lute = "<version>" instead, or check where the hashes came from.	64
global-configuration.invalid, global-configuration.unreadable	Your config.toml is not valid TOML, or cannot be read.	Fix the file the message names.	64
global-configuration.test-blocked	Your config.toml sets something under [test] that names a project’s files, such as roots.	Move it to that project’s luau-run.toml.	64
luau-run-home.invalid	LUAU_RUN_HOME is not a full path to a folder that exists, or LUAU_RUN_CACHE_ROOT is not a full path.	Set the variable the message names to a full path, such as D:\luau-run, or unset it.	64

Any other test. or command. code ending in -invalid, -too-many or -field-unknown means a setting has the wrong name, type or value. The message names it, and Project settings says what each one takes. These exit 64.

init

Code	What happened	What to do	Exit
init.answer-missing	init had no terminal to ask at, and an option was missing.	Run the command it prints, or luau-run init --interactive.	64
init.recommendation-thin	--accept-recommended was given, but the project gave too little to recommend from.	Answer the questions, or give the options the message names.	64
init.test-root-missing	A --test-root folder does not exist, and the project has specs somewhere else.	Name the folder the tests are in.	64
init.already-initialized	This folder already has a luau-run.toml.	Edit that file. init never changes one.	64

Any other init. code means init was given an option or answer it cannot use. The message says which. These exit 64.

pin

Code	What happened	What to do	Exit
pin.arguments-invalid	pin was given something other than lute <version>.	Run luau-run pin lute <version>.	64
pin.version-invalid	The version is not a version, such as v1.0.0.	Leave out the leading v.	64
pin.project-missing	There is no luau-run.toml in this folder.	Run luau-run init first.	64
pin.no-release	That Lute release has no archive for a platform Luau Run needs.	Check the version, or pick another release.	64
pin.project-form	luau-run.toml writes [tools] in a form pin cannot rewrite.	Write [tools] as a table, as the message shows.	64

Choosing tests

Code	What happened	What to do	Exit
test.arguments-invalid	test was given an option it does not take, or a value it cannot use.	Fix the command. luau-run --help lists the options.	64
test.discovery.root-invalid	A root or a path on the command line does not exist or is a link, or a named file does not end in .spec.luau or .test.luau.	Fix the path.	64
test.discovery.outside-root	A path on the command line is outside the project’s folder.	Run from a folder that holds it, or name a path inside the project.	64
test.discovery.unreadable	A test file or folder could not be read. The message names it and why.	Fix its permissions, or leave it out of roots.	64
test.discovery.source-not-utf8, test.discovery.source-changed, test.discovery.source-too-large, runtime.source-too-large	A test file is not UTF-8, changed while it was read, or is larger than 4 MiB. Only that file is refused.	Save it as UTF-8, run again once nothing is writing to it, or split it.	4
runtime.selection-missing	Nothing chose a runtime for a file. Outside a folder with luau-run.toml, nothing is set at all.	Run from the folder with luau-run.toml, or set default-runtime.	64
selection-empty	No file under the roots is named *.spec.luau or *.test.luau.	Rename the tests, or point roots at their folder.	4
test.runner-runtime-incompatible	A file’s runner runs on one runtime, and the file was given another.	Change the header, option or rule the message names.	4
runtime.selector-invalid, runtime.selector-duplicate	A file’s -- luau-run: header names an unknown runtime, or appears twice. Only that file is refused.	Fix the header.	4

Project commands

Code	What happened	What to do	Exit
command.unknown	The first word is not a Luau Run command, or one luau-run.toml declares.	Fix it. The message names the closest command, and luau-run --help lists them.	64
command.arguments-invalid	doctor was given an option, or plan or run was given no --request file.	Fix the command. luau-run --help lists the options.	64
command.runtime-argument-invalid	runtimeArgs holds an option that could replace the entry or run other code, such as Bun’s --eval.	Remove it.	64
command.tool-*, command.rokit-manifest-*	A tool the command needs is not pinned, not installed, pinned by Foreman, or named by a path that is not there.	Do what the message says, such as rokit install.	64
command.timeout	The command ran past its timeout-seconds.	Find what hangs, or raise timeout-seconds.	2

Running tests

Code	What happened	What to do	Exit
no-tests	A file ran but registered no test, which Jest counts as a failure.	Add a test, or check which runner rule sent the file to Jest.	1
suite.execution	A Jest spec threw outside its tests, such as in a require at its top.	Fix the error the message gives. A missing packages folder means the packages are not installed.	1
suite.result-limit	A Jest spec has more than 1,024 tests, too many to keep each result. The message still gives its counts.	Split it into smaller specs.	1
std-test-unreadable	A script test uses @std/test, and this Lute does not let Luau Run read its cases.	Use the Lute luau-run setup installs, or report it with the Lute version.	1
spec-clock.*	A test file ran past spec-timeout-seconds, 120 seconds unless set. With spec-clock.never-yielded it never yielded, so its process was ended, and the files after it in that process did not run.	Find what hangs, or raise spec-timeout-seconds. when-spec-times-out sets what happens to the rest of the file’s process.	2
jest-suite.invocation-terminal-missing	A Jest runner on Lute was stopped before it reported every file. The line above the code says why, such as the run’s time limit.	Do what that reason needs, such as raising timeout-seconds.	2
result-artifact.missing	A test process ended before writing its result, such as a script test that calls process.exit, or a crash.	Read the last lines it printed, shown below the error.	3
jest-suite.runner-crashed	A Jest runner on Lute ended before a file’s result, such as when a spec calls process.exit. The files after it run in a fresh runner.	Find what ends the process in that file.	3
entry-provider.path-too-long	A script test’s full path is 260 characters or more, and Lute on Windows cannot open it.	Move the project to a shorter folder, or shorten the path.	4
jest-toolchain.executable-unavailable	Lute or the supervisor is not installed at the path the message names.	Run luau-run setup.	4
jest-toolchain.identity-mismatch	A tool file is not the build Luau Run pins, such as a supervisor you built.	Run luau-run setup. For your own supervisor, see The supervisor’s pin.	4
tool-choice.path-missing	A tool path you set, in a variable or under [paths], has nothing at it.	Fix the path, or remove it.	4
tool-choice.not-a-program	A Lute path you set is not a Windows x64 program.	Point it at lute.exe.	4
tool-choice.version-missing	The Lute version the project or your config.toml names is not installed.	Run luau-run setup, in the project’s folder if the project names it.	4
tool-choice.jest-portable-not-carried	[tools] jest-portable names a version this Luau Run does not carry. Its Jest specs are refused, and its script tests still run.	Name the version Luau Run carries, or remove the setting.	4
jest-precompiled.unavailable, jest-precompiled.test-globals-unavailable	The Jest runner for Lute is not installed. The second code is for surface = "test-globals".	Run luau-run setup.	4
jest-precompiled.archive-damaged, jest-precompiled.runner-damaged	The Jest runner for Lute, or its archive, is not the pinned file.	Run luau-run setup to repair it.	4
jest-precompiled.path-not-ascii	The Jest runner for Lute sits under a folder whose name is not plain ASCII, such as an accented user name, so Lute cannot find it.	Set LUAU_RUN_HOME to a folder whose path is plain ASCII, then run luau-run setup.	4

Starting test programs

test and setup can both give these. From setup they exit 4. The two supervisor. rows with ... show the start of the message, not a code.

Code	What happened	What to do	Exit
launch.runtime-missing	Lute needs the Microsoft Visual C++ Redistributable (x64), and it is not installed.	Install it from Microsoft’s download, then run the command again.	3
launch.access-denied	Windows denied access to the test program (error 5), often because of antivirus or a security policy.	Allow the file, or ask whoever manages this computer.	3
launch.blocked-policy	App Control or a group policy blocked the test program (error 4551 or 1260).	Ask whoever manages this computer to allow it.	3
launch.blocked-antivirus	Antivirus blocked or removed the test program.	Allow it in your antivirus, then run luau-run setup.	3
launch.being-written	The test program was still being written or scanned (error 32).	Run the command again.	3
launch.executable-mismatch	The test program changed after it was installed.	Run luau-run setup to repair it.	3
launch.blocked	Windows did not start the test program, for a reason Luau Run does not know. The message names the error.	Look the error up, or report it.	3
supervisor.input: message.schema: ...	Luau Run built a message its own rules reject, usually with a path that is not absolute.	Report it if Luau Run made the path.	3
supervisor.protocol-error ... message.schema in phase launch	The supervisor is older than this luau-run.exe.	Run luau-run setup, or point LUAU_RUN_SUPERVISOR_EXE at the matching build.	3
supervisor.unresponsive	The supervisor did not finish in time. This is a fault in Luau Run or the computer, not a test failure.	Run again, and report it if it happens again.	3

Roblox Studio

Finding Studio and Rojo

Code	What happened	What to do	Exit
studio.platform-unqualified	The Studio lane runs only on Windows.	Run Studio specs on Windows.	4
studio.framework-unconfigured	This luau-run.exe does not carry Jest for Studio, and LUAU_RUN_JEST_ROBLOX_ROOT names none.	Install a release build, or set LUAU_RUN_JEST_ROBLOX_ROOT to the Jest-Portable Studio archive or its folder.	4
studio.supervisor-unavailable	The supervisor is not installed.	Run luau-run setup.	4
studio.not-found	No installed Roblox Studio was found.	Install Studio, or set LUAU_RUN_STUDIO_EXE. luau-run doctor lists where it looked.	4
studio.explicit-missing	The Studio path you set is gone, such as after a Studio update.	Remove it to use the Studio Luau Run finds. luau-run setup offers to remove a saved variable.	4
studio.rojo-explicit-missing	The Rojo path you set is gone.	Fix it, or remove it to use the Rojo the project pins.	4
studio.input-missing	A Studio or framework path you set, such as LUAU_RUN_JEST_ROBLOX_ROOT, names nothing.	Fix the path, or unset it.	4
studio.current-unusable	Studio’s current build cannot run right now, such as during an update.	Try again in a moment, or set LUAU_RUN_STUDIO_EXE.	4
studio.rojo-not-found	No rokit.toml, aftman.toml or foreman.toml in this folder or above pins Rojo, and none is on PATH.	Run rokit add rojo-rbx/rojo, or set LUAU_RUN_ROJO_EXE.	4
studio.rojo-not-installed	The project pins a Rojo that Rokit has not installed.	Run rokit install in the project’s folder.	4
studio.rojo-launcher, studio.rojo-foreman	The Rojo found is a tool manager’s launcher, or Foreman pins it.	Pin Rojo in rokit.toml, or set LUAU_RUN_ROJO_EXE.	4
studio.surface-unavailable	surface = "test-globals" is set, and Studio needs the full surface.	Remove that setting for Studio runs.	4

Building the test place

Code	What happened	What to do	Exit
studio.project-missing	The rojo-project file does not exist.	Fix the path under [test.roblox-studio].	4
studio.project-not-a-place	The rojo-project builds a model, not a place.	Name a project whose root is a DataModel.	4
studio.project-packages-missing	The Rojo project mounts a folder that does not exist, usually packages that were never installed.	Run pesde install or wally install.	4
studio.sourcemap-failed	Rojo could not write the sourcemap, such as Rojo 7.6 with a project that mounts a path outside its folder.	Do what the message says. Rojo 7.7.0 writes those sourcemaps.	4
studio.instance-require-unresolved, studio.instance-require-ambiguous, studio.instance-require-not-a-module	A require by instance path names something the project does not mount, a name two children share, or something that is not a ModuleScript.	Fix the path, or mount what it names.	4
studio.instance-require-unsupported-file	A required module is built from something run-server cannot build as Rojo does, such as YAML or a model file. JSON and TOML modules lists each case.	Use data-model = "edit" with rojo-project set.	4
studio.capture-dynamic-require	A spec has a require whose path is computed. The message gives the line.	Write the path out, or use data-model = "edit" with rojo-project set.	4
studio.capture-alias-missing	A require names a Lune or Lute builtin, or an alias no .luaurc up to the project’s folder declares.	Send that spec to Lute with a runtime rule, or declare the alias.	4
studio.capture-aliases	A .luaurc an aliased require reaches cannot be used: Luau cannot read it, a .config.luau sits beside it, its aliases form a loop, or Lute skips it because a module beside its folder has the same name. The message gives the reason and the files.	Fix the file, keep one configuration file in that folder, or rename the folder or the module.	4
studio.capture-config-luau	An aliased require’s search reaches a .config.luau, and Luau Run does not run configuration code.	Declare the alias in a .luaurc.	4
studio.capture-module-resolution	A required module has no file behind it, or more than one.	Install the project’s packages, or keep one file.	4
studio.capture-module-collision	Two files get one name in Studio, such as Thing.lua beside Thing.luau.	Rename or remove one.	4
studio.capture-outside-root	A file the specs need is outside the folder the run started in, or behind a link, as in a pesde workspace.	Put luau-run.toml in a folder that holds the specs and every file they need, such as the pesde workspace’s, and run from there.	4
studio.capture-linked-input	A file in the folder LUAU_RUN_JEST_ROBLOX_ROOT names is behind a link.	Name a folder that holds the files themselves.	4
studio.capture-link-loop	A link leads back to a folder above it.	Remove the link, or point it elsewhere.	4
studio.capture-total-limit	The test place’s files pass 10,000 files or 256 MiB.	Use a smaller Rojo project, or run-server.	4
studio.capture-alias-limit	A .luaurc is over 1 MiB or declares over 4,096 aliases, or the ones the run reads declare over 100,000 in all.	Trim the file.	4
studio.capture-changed	A file changed, vanished or appeared while the test place was built.	Run again once nothing is writing to the project.	4
place.placed-service-unsupported	A module sits under a service the test place does not build, such as Players.	Move it to a service such as ReplicatedStorage.	4
place.placed-name-reserved	A module sits at a name the test place keeps for Luau Run: ServerStorage._LuauRun, ServerScriptService.TestBootstrap or Workspace.Baseplate.	Use data-model = "edit" with rojo-project set.	4

Your whole place, in edit

Code	What happened	What to do	Exit
studio.spec-unmounted	A spec lies outside what the Rojo project builds.	Mount its folder, or leave it out of roots.	4
studio.instance-name-ambiguous	Two Instances share a name where Luau Run has to pick one. The message names both files.	Rename one, or mount only one.	4
place.runner-service-declared	runner-service names a service the project declares.	Pick a service the project leaves free, or remove the setting.	4
place.runner-service-unavailable	The project declares TestService, ServerStorage and ReplicatedFirst, so none is left for Luau Run.	Leave one of them out of the project.	4

During the run

Code	What happened	What to do	Exit
studio.member-result-too-large, studio.member-runner-failed	A file’s result passed 2 MiB, all of them passed 16 MiB, or a file’s runner failed. The files after it still ran.	Split the file, or report it with what was printed.	3
studio.boot-timeout	Studio did not start the tests within boot-timeout-seconds, 60 seconds unless set. It may be signed out or showing a dialog.	Run with --studio-visibility visible to see it. For a place that is slow to open, raise boot-timeout-seconds.	3
studio.suite-failed	The test runner inside Studio failed outside any one file, such as when a module it needs errors while loading. The report shows Studio’s error beside the files that had not finished.	Fix the error it shows. The module’s own error comes before Studio’s “Requested module experienced an error while loading”.	3
studio.session-failed	Studio ended before every result and its cleanup came back.	Run again. If it repeats, watch with --studio-visibility visible and report it.	3
studio.session-deadline	The Studio session reached the run’s time limit.	Look for a spec that never finishes, or raise timeout-seconds.	2

Setup and downloads

pin lute and update download too, and give the same download. codes. --from is a setup option.

Code	What happened	What to do	Exit
setup.answer-missing	setup had no terminal to ask at.	Run the command it prints, usually luau-run setup --accept-recommended.	64
setup.answer-invalid	The answer was not one setup could use.	Run the command it prints.	64
setup.arguments-invalid, setup.part-invalid, setup.part-required	An option is unknown, --from has no folder, a part other than jest-lute was named, or --without core was given.	Fix the command. luau-run --help lists the options.	64
setup.home-not-ascii	The same as jest-precompiled.path-not-ascii, found before anything is fetched.	Set LUAU_RUN_HOME as that row says, or run the command it prints to skip the Jest runner for Lute.	64
setup.missing	A file setup needs is not in the --from folder, needs a download while offline, or is not in this build.	Do what the message says.	4
setup.from-wrong-version	The --from folder has a file with the right name but the wrong version.	Put that release’s own file in the folder the message names, or run without --from.	4
download.unreachable, download.status	A download did not finish, or GitHub refused it. A certificate that reads as expired usually means a wrong clock, or a proxy or antivirus that inspects HTTPS.	Check the connection and the date and time, then run the command again. Or use --from.	4
download.intercepted	Something other than GitHub refused the download, such as a proxy.	Ask for github.com and release-assets.githubusercontent.com to be allowed, or use --from.	4
download.proxy-denied	The proxy wants a login Luau Run cannot give.	Use a proxy with no login, or use --from.	4
download.web-page	A web page came instead of the file, usually a network sign-in page.	Sign in to the network in a browser, then run the command again.	4
download.too-large, download.redirect-refused	The download was larger than expected, or a redirect led somewhere Luau Run will not follow. Something may be changing downloads.	Use --from.	4
integrity.mismatch	A downloaded file is not the one Luau Run expects, so it was not installed.	Run the command again. If it happens again, something may be changing downloads.	4
integrity.archive-*	An archive broke one of Luau Run’s unpacking rules, such as an unsafe name or a link.	Download the release asset again, or report it.	4
setup.probe-failed	The Jest runner for Lute started but failed its check.	Report it with what luau-run setup printed.	4
setup.probe-not-started	The Jest runner for Lute could not start for its check, such as on a full disk.	Free space if the message says so. Otherwise run luau-run setup again, and report it if it happens again.	4
setup.probe-refused	test refused to run the new Jest runner for Lute here. The message says why.	Do what it says, then run luau-run setup again.	4
store.held	Another setup is running, or another program, such as antivirus, holds a file in the home.	Wait, then run luau-run setup again.	4
store.unwritable	Luau Run could not write to its home: the disk is full or permissions forbid it.	Free space, fix the permissions, or set LUAU_RUN_HOME. Then run luau-run setup again.	4
store.disk-full	The home’s disk has less free space than setup needs. Nothing was written.	Free space, or set LUAU_RUN_HOME to a folder on another disk. Then run luau-run setup again.	4
store.collision	Two tools share a folder name in the store.	Report it.	4

Install, uninstall and update

Code	What happened	What to do	Exit
self-install.arguments-invalid, uninstall.arguments-invalid	An option is not valid, such as setup options with --no-setup.	Fix the command. luau-run --help lists the options.	64
self-install.unbuilt	self-install was run from source, with no luau-run.exe to place.	Build one with bun run build:windows. See Building from source.	64
uninstall.path-unwritable	uninstall could not take bin off your Path, so it removed nothing.	Run it again, or remove the entry in Settings, under Environment Variables.	4
install.not-installed	The install script did not install Luau Run in this home.	Remove it the way it was installed, such as with Rokit, or delete the luau-run.exe you placed.	4
install.path-recorded	--no-modify-path was given, but the install added a Path entry.	Run luau-run uninstall without it, or remove the entry yourself first.	4
install.record-unreadable	installation.json is from a newer Luau Run, or damaged. Nothing changed.	Use the newer Luau Run’s script, or delete a damaged installation.json and install again.	4
update.answer-missing	update would ask, but there is no terminal, or --json was given.	Run the command it prints, which adds --accept-recommended.	64
update.arguments-invalid	The options do not go together, or --version is not a version.	Use luau-run update, update --check, update --rollback or update --version <version>.	64
update.not-script	This copy is not the one in Luau Run’s bin folder, such as one from Rokit or from source. Nothing changed.	Update it the way it was installed, or install with the script.	4
update.not-this-install	installation.json names another build, such as after another update finished first.	Run the luau-run.exe in Luau Run’s bin folder, or install again with the script.	4
update.release-unknown	No published release was found.	Try again later, and report it if it happens again.	4
update.older	The release is older than this Luau Run, and update never goes back by itself.	Use update --version <version> to go back, or update --rollback for the build before.	4
update.no-asset	The release has no build for this platform.	Stay on this build.	4
update.not-signed	The release’s manifest has no signature this Luau Run can read, such as one cut short, or one by keys newer than this build. Nothing was installed.	Run luau-run update again. If it happens again, reinstall with the install script.	4
update.signature-mismatch	The release’s manifest does not match its signature. Nothing was installed.	Run luau-run update again. If it happens again, report it, and do not install that release by hand.	4
update.unknown-key	The release is signed with a key this Luau Run does not know.	Reinstall with the install script.	4
update.unkeyed	This build carries no release keys.	Install releases with the install script.	4
update.manifest-invalid, update.version-mismatch	The release’s manifest is unreadable, or for another version. Nothing was installed.	Report it with what luau-run printed.	4
update.smoke-failed	The new build, run once, said it is another build, so it was not placed.	Report it with what luau-run printed.	4
update.launch-failed	Windows did not start the new or earlier build, such as when antivirus blocks it.	Allow programs in Luau Run’s store, then run the same luau-run update again.	4
update.setup-failed	The new build’s setup failed, so it was not placed.	Run the same luau-run update again, and report it if it happens again.	4
update.no-previous, update.previous-gone	update --rollback found no earlier build, or its copy is gone.	Name the version: luau-run update --version <version>.	4

How a refusal looks

• test before a run, update, pin, self-install and uninstall print one error[<code>] line on standard error at a terminal, and a JSON object otherwise.
• Inside a run, a refusal is part of the report, as REFUSED with a Code: line.
• setup prints a message, what it is about and why, then a Code: line.
• init prints a message, and gives its code only with --json.

Exit codes of other commands

Running tests gives test’s exit codes. The other commands:

• init exits 0 when the file was written, 1 when you cancel, and 64 when it refuses.
• setup exits 0, 1 when you answer no, 2 when Ctrl+C stops it, 4 when it refuses, and 64 for a usage problem.
• self-install, uninstall and update exit 0, 4 when they refuse and 64 for a usage problem. update also exits 0 when you answer no. Once self-install has placed the program, it exits with its setup’s code.
• pin lute exits 0, 64 when it refuses, and 4 when a download fails.

An internal error, in any command, prints one error[...] line, usually error[command.failed], and exits 70. Report it with that line.