Troubleshooting

Diagnose a busy port, missing WASM file, stripped headers, or unsupported format.

The page does not respond

Check the port: published host port 2501 for Docker, loopback port 2499 for Vite.
Inspect the container:

docker compose ps
docker compose logs --tail 100 swissknife

The health check requests http://127.0.0.1:2501/ inside the container. An unhealthy status points to Nginx, not your browser.

The audio/video engine does not load

open /ffmpeg/ffmpeg-core.wasm: it must return 200 with application/wasm;
check Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp on the document;
a reverse proxy may have stripped these headers: see Reverse proxy;
the first load downloads about 32 MB, so a slow connection may hit the 120-second timeout;
image-only conversions do not need the engine: PNG to JPG may succeed while MP3 fails.

The console, available from the Console button, shows the FFmpeg log.

`docker compose up` fails

host port already in use: change only the left-hand host port and keep the project port on the right;
GHCR image unavailable: build with docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build;
insufficient permissions to run Docker.

A file is rejected

PDF, text, and unknown types are not added to the queue. GIF is handled as video. TIFF/BMP is handled as an image only when the browser can decode it. See Formats.

The demo does not show its badge

You are probably using the regular product (npm run dev or the GHCR image). The badge is included only in build:demo / Vercel.

A conversion exhausts the tab

The warning above 50 MB is expected. Close other tabs, convert one file at a time, or reduce the source file. There is no remote queue to offload memory usage.

Product checkout quality gate

npm run lint
npm test
npm run build