Troubleshooting

Configuration cannot be loaded#

Use simpcn.config.ts with a default export. Run commands in the application directory, or select the file explicitly:

npx simpcn plan --config ./simpcn.config.ts

Remove unknown fields. MinIO and R2 require storage.endpoint; R2 requires region: 'auto'. The endpoint is the upload API, not the public delivery URL. State and manifest paths must be distinct and outside the asset directory.

Build says an asset is missing or stale#

Build state must match the current asset bytes, hash, size, MIME type, storage key, cache policy, and target. Migrate the same application directory and target before building:

npx simpcn plan --check-remote
npx simpcn migrate
npm run build

If migration reports a conflicting remote key, review the object before explicitly using migrate --overwrite. Do not hand-edit verification records to bypass failures. Commit the updated simpcn/deployment-state.json with the matching assets so CI receives it. Check that Git ignores only simpcn/.build/ and temporary state files, rather than the entire simpcn directory. Existing configs with custom stateFile paths still use those paths.

A production URL is still local#

Confirm the framework wrapper/plugin is installed and that a new production build was deployed after migration. Check the reference support matrix. Dynamic paths need the framework’s assetUrl() helper; arbitrary strings and custom component props are not automatically handled.

Next.js CSS URLs stay local. For next/image, inspect diagnostics for custom loaders, spread props, or optimization conflicts. Vite’s Simpcn plugin must run before the JSX compiler, and the configured root must match publicDir.

Uploads work, but the asset URL fails#

Open the configured delivery URL independently without upload credentials. Check bucket/CDN read access, origin mapping, prefix, filename case and encoding, and CORS for fonts. Ensure publicBaseUrl includes the delivery prefix exactly once.

Successful historical verification does not prove current public reachability. An upload API endpoint may require credentials and is not automatically a browser-facing URL. Simpcn does not change bucket policies or purge stale CDN caches.

Migration stopped partway through#

Check authentication, endpoint, bucket, and provider errors. Successful verified progress is retained; rerun migration after resolving the failure. Authentication and network errors are not treated as absent objects. Large files above 5 GiB require another upload strategy.

npx simpcn plan --check-remote --json
npx simpcn migrate --json

Structured output can help diagnose failures. Redact credentials, private URLs, and sensitive file names before sharing logs. Use npx simpcn --help to confirm available options.

Report a reproducible issue#

Open a GitHub issue with the package and Node versions, framework/bundler, minimal supported reference, expected output, and relevant error message. Include a small reproduction when possible; never include credentials or deployment-state artifacts containing private information.