Troubleshooting
Find the message you see, then its cause and fix.
Start with the doctor
Run ./gradlew svelteDoctor first: it checks the frontend setup and lists most problems on this page at once. Add --fix and it repairs the ones that need no decision from you: a missing #api import, a tsconfig.json that does not extend $app/tsconfig, $lib imports left over from SvelteKit 2, and a node_modules folder whose packages lost their files, which it deletes so the next build installs it again. It prints each change as FIXED, and everything else stays a finding for you. See svelteDoctor.
At a glance
| You see | Go to |
|---|---|
| The build fails before the frontend is built | Build |
| The app does not start | Startup |
| A request answers 403, 413, 429 or 503 | Requests |
Something is off while svelteDevAll runs | Development |
| A check, hook or browser test fails | Checks and tests |
Build
ktor-svelte found no lockfile
- Cause: the frontend has no
bun.lock,pnpm-lock.yaml,package-lock.jsonoryarn.lock, so the plugin cannot tell which package manager to use. - Fix: install the dependencies once with your package manager, or set
svelte { packageManager = PackageManager.Bun }.
ktor-svelte could not find bun on PATH
- Cause: the package manager the lockfile asks for is not installed, or Gradle cannot see it.
- Fix: install it and restart the Gradle daemon with
./gradlew --stopso it picks up the newPATH, or setpackageManagerto one you have. - Or: let the plugin download Bun for you with
svelte { bunVersion = "1.3.14" }. See Pin Bun.
ktor-svelte found no HTML files
- Cause: the frontend build produced no pages where the plugin looked.
- Fix: check that the frontend uses
adapter-static, and thatsvelte { outputDir }matches the adapter'spagesoption. The default for both isbuild.
svelte.outputDir must be a path inside svelte.frontendDir
- Cause:
outputDirpoints outside the frontend folder. - Fix: give it relative to
frontendDir, such asoutputDir = "build".
ktor-svelte has no setting 'x' in svelte
- Cause: a Groovy build script assigns a setting that does not exist, usually a typo.
- Fix: the message names the closest setting and lists all of them. See Gradle settings for what each one does.
Frontend libraries are out of sync
- Cause:
build.gradle.ktschanged the frontend libraries, butpackage.json, the lockfile or the generated files were not updated. - Fix: run
./gradlew svelteSyncand commit the result.
ktor-svelte generates vite.config.ts, but found your own version
- Cause: the plugin needs to own
vite.config.tsand the hooks files once frontend libraries are on. - Fix: move your own Vite settings to
vite.user.ts, merge custom hooks by hand, delete those files and runsvelteSync.
Generated TypeScript is out of date
- Cause:
checkrunssvelteVerifyTs, which found that a route or DTO changed but the committed client did not. - Fix: run
./gradlew svelteGenerateTs, or start the app in development mode, and commit the files infrontend/src/lib/api.
ktor-svelte found secret values in the frontend build
- Cause:
svelteVerifyLeaksfound the value of a secret environment variable or a.enventry in the built files. - Fix: read that value on the server only. A value that is meant to be public belongs in
svelte { buildEnv }, or gets a name that starts withPUBLIC_. See Secrets in the frontend build.
undefined is not an object (evaluating 'ts.sys.readFile')
- Cause: the frontend uses TypeScript 7, which SvelteKit 3 cannot load yet. It usually arrives through an automatic dependency update.
- Fix: set
"typescript": "^6.0.0"infrontend/package.jsonand install again. - Keep it away: tell your update bot to ignore major versions of
typescript.
Cannot find module 'rolldown/parseAst', or another package that is installed
- Cause: the install was cut short: the package's folder exists in
node_modules, but its files do not, and the package manager still reported success../gradlew svelteDoctornames the packages that lost their files. - Fix: run
./gradlew svelteCleanand install again. - If they come back empty: the package manager's cache is the cause, so clear it with the command
svelteDoctorprints, such asbun pm cache rm, and install once more.
The frontend build failed with exit code 1
- Cause: ktor-svelte hides the package manager and Vite output while it succeeds and prints all of it when it fails, above this message. The real error is there.
- Fix: to see the output every time, add
-Psvelte.verbose=true.
Startup
ktor-svelte found no frontend build
- Cause: the app runs in production mode, but the JAR has no frontend in it.
- Fix: build it with the Gradle plugin and without
-Psvelte.skip=trueor-Psvelte.dev=true. - During development: start it with
-Dio.ktor.development=true, or usesvelteDevAll, which does that for you.
ktor-svelte manifest has format version 2, but this runtime reads version 1
- Cause: the Gradle plugin and
ktor-svelte-serverhave different versions. - Fix: use the same version for both. With
addRuntimeDependencyon, which is the default, the plugin adds the matching runtime for you.
ContentNegotiation is already installed
- Cause: you install
ContentNegotiationyourself and also list formats intransport { }. - Fix: keep one of the two. The same applies to
Compressionandcompression().
RequestBodyLimit is already installed, or RateLimit is already installed
- Cause: ktor-svelte installs these plugins for its body and rate limits.
- Fix: to use your own, set
maxApiBodySize = nullorrateLimit { enabled = false }.
ktor-svelte will not proxy to this URL because it is not on this machine
- Cause:
dev { url }orKTOR_SVELTE_DEV_SERVERpoints at another host. - Fix: use a loopback address, or set
dev { allowRemote = true }if you trust that machine.
Install the Svelte plugin before calling svelte() in routing
- Cause: with
routing = SvelteRouting.Manual,svelte()ran before the plugin was installed. - Fix: call
install(Svelte)before therouting { }block that callssvelte().
errorCodes, currentUser, permissions or preferences is already set
- Cause: an app has one enum of error codes, one kind of signed-in user, one enum of permissions and one class of preferences, and one of them was declared twice.
- Fix: keep one declaration in
install(Svelte).
The Ktor route GET /about hides the frontend page about.html
- Cause: a route in your app answers the same path as a prerendered page, so the page is never served.
- Fix: move the route under your API prefix, or rename the page.
Requests
403: Cross-origin API request refused
- Cause: the origin check refused a write from another site.
- Fix: if that site is yours, such as a separate admin frontend, add it with
allowedOrigins("https://admin.example.com"). - Behind a proxy that changes the host: install
XForwardedHeadersso the app sees the host the browser used. See Security.
413: Request body is larger than the limit
- Cause: API bodies are limited to 1 MiB.
- Fix: raise
maxApiBodySizefor apps that accept uploads.
400: Request JSON is nested deeper than 64 levels
- Cause: the JSON body nests deeper than
maxJsonDepth, or has a string longer thanmaxJsonStringLength. - Fix: raise the limit if your API really takes such bodies, or set it to
null. See Security.
429: Too Many Requests
- Cause: a client sent more than 120 writes to API paths in a minute, or hit a named limit.
- Behind a proxy: install
XForwardedHeaders, or all users share one limit. - Fix: raise
rateLimit { apiWrites = ... }if your app writes a lot.
503 in development: no Vite and no build
- Cause: the app runs in development mode, Vite is not running and there is no frontend build.
- Fix: start everything with
./gradlew svelteDevAll, or Vite alone with./gradlew svelteDev.
403: The dev proxy only answers requests from this machine
- Cause: you opened the app from another device while it runs in development mode.
- Fix: set
dev { allowRemote = true }on a network you trust.
A page shows a blank screen after a deploy
- Cause: the browser has an old page that loads chunks which no longer exist. ktor-svelte answers those with 404 on purpose, so SvelteKit reloads the page.
- Fix: if it does not reload, check that nothing in front of the app caches HTML: pages are sent with
Cache-Control: no-cache.
Development
The browser logs a WebSocket error for HMR
- Cause: without
server.hmr.clientPortinvite.config.ts, Vite's client first tries Ktor's port. Hot reload still works after one error. - Fix: set
server: { hmr: { clientPort: 5173, protocol: 'ws' } }. Projects fromsvelteInitalready set it.
A port is already in use
- Cause: a Vite or app process from an earlier run is still alive, usually because a terminal was killed.
- Fix:
svelteDevAllstops what an earliersvelteDevAllleft running by itself. For anything else, run./gradlew --stop, or stop the process on that port. See When a port is still in use.
Port 5173, which Vite needs, is in use by another program
- Cause: a program
svelteDevAlldid not start holds Vite's port or the debug port, so the task stops before starting anything. - Fix: stop that program, or use another port with
svelte { dev { port = 5174 } }ordev { debugPort = ... }.
Types do not update after a Kotlin change
- Cause: the client is generated when the app starts in development mode with
generateTs = true. - Fix: with
svelteDevAll, that happens after every Kotlin change. With separate terminals, restart the app, or run./gradlew svelteGenerateTs.
The browser does not trust the HTTPS certificate in development
- Cause: the development certificate authority in
~/.ktor-svelte/dev-httpsis not in your trust store yet. - Fix: run the command the first
svelteDevAllprinted, such ascertutil -addstore -user Rooton Windows. In Firefox, importca.crtunder Settings, Certificates, Authorities. See HTTPS in development.
The console warns with window_fetch_in_load
- Cause: an API call in a
loadfunction does not use SvelteKit'sfetch. - Fix: use
apiWith(event), or pass{ fetch }as the last argument../gradlew svelteVerifyLoadsfinds every such call. See In load functions.
The page signs me out after every Kotlin change
- Cause: your sessions do not survive a restart, such as with a signing key that is generated at startup.
- Fix: read the key from the environment, so it stays the same across restarts. To stop pages from reloading their data after a restart, set
dev { refreshAfterRestart = false }.
Checks and tests
svelteDoctor found problems to fix
- Cause: at least one finding is an
ERROR. - Fix: each line says what to do.
./gradlew svelteDoctor --fixrepairs the ones that need no decision.
The pre-commit hook already exists and was not written by ktor-svelte
- Cause: another tool installed a pre-commit hook, and
svelteGitHooksnever replaces it. - Fix: call
./gradlew formatCheck svelteVerifySyncfrom that hook yourself, or delete it and runsvelteGitHooksagain.
Not inside a git repository, so there is nowhere to install a hook
- Cause:
svelteGitHooksran in a folder that is not a git clone. - Fix: run
git initfirst, or run the task in the clone.
The app did not answer within 60 seconds
- Cause: a browser test,
svelteSmokeTestorsvelteVerifyA11ystarted the packaged app, and it did not answer in time or stopped. Usually a variable or a database it needs is missing. - Fix: read the app's output:
build/ktor-svelte/smoke-test.logfor the smoke test, the file inapp.login a browser test. Give the app what it needs, or more time with--start-secondsfor the smoke test.
The app ignores the port in tests
- Cause: the port is passed as the
PORTvariable and as-port, and the app reads neither. - Fix: read one of them, as
EngineMaindoes with-port.
Still stuck?
Open an issue with the full message, your install(Svelte) and svelte { } blocks, and the output of ./gradlew svelteDoctor.