Troubleshooting

Ask your agent to debug it

Read https://edgestore.dev/docs/troubleshooting.md and inspect my existing EdgeStore integration. Explain the cause before making changes.

Problem:

[Describe the problem]

Include the error message and steps to reproduce it.

Route not found or method not allowed

Open the handler's health endpoint. With the default Next.js route it is http://localhost:3000/api/edgestore/health. Use your backend origin and mounted path for other adapters.

For a 404 or 405, check the catch-all route and GET/POST exports. Match the React provider's basePath to the mounted endpoint, including any proxy prefix.

Credentials or access denied

Confirm the backend loads the expected env file before creating the storage provider, and that the keys belong to the intended project.

For protected buckets, check the application's authentication context and access rules.

Check the browser console for errors and the failing request and response in the Network panel, then use Error handling to identify validation, size, or access errors. Confirm that the React provider wraps the upload component.

For separate frontend and backend origins, allow the intended frontend origin in CORS and check the adapter's cookie and deployment requirements.

Enable server debug logging

Enable debug logging to inspect server-side failures. Debug output includes application context and cookies. Remove those values before sharing logs.

Inspect the application with the CLI

edgestore --cwd <app> agent context --json
edgestore --cwd <app> doctor --offline --json

Use the backend directory for server checks in a split workspace. agent context reports installed versions and local references. doctor --offline inspects configuration without authenticating or running the application.

Try an example app

Run an example close to your framework to compare with your application.

For Next.js:

npx degit edgestorejs/edgestore/examples/next-basic#main edgestore-example
cd edgestore-example
npm install

Add your EdgeStore keys to .env.local as shown in Quick start, then run:

npm run dev

Still blocked?

Ask in Discord or open an issue with your framework, installed EdgeStore versions, and the error.