DeHub Developer Troubleshooting

The most common problems, and how to fix them. The checker on dehub.io/apps/dev tells you which field is wrong in plain words, so start there.

Manifest problems

Message	Fix
Not found at /.well-known/dehub.json	Serve the file at exactly that path over https. Many hosts hide folders that start with a dot; allow `.well-known`.
Found, but it is not valid JSON	Paste the file into a JSON checker. Trailing commas are the usual cause.
homeUrl must be on your domain	`homeUrl` has to be on the same domain that serves the manifest.
ownership.signature: Signed by 0x…, not 0x…	Sign with the same wallet you put in `ownership.address`, or use the Sign button on /apps/dev.
The app must be served over https	Localhost and http work only in developer preview (Launch on /apps/dev), not for submitting.

When the app runs

Problem	Fix
The splash screen stays for 8 seconds	Call `dehub.ready()` once your first screen is on.
`Not running inside dehub`	The page was opened on its own. Check `dehub.isInDehub()` and show a normal web version.
`signin` error	The person is signed out of DeHub. Ask them to sign in, or let them use your app as a guest.
`unsupported` on pay or addApp	Developer previews cannot take payments or be added. Submit the app first.
The app looks stretched on desktop	It should not: DeHub runs mini apps in a phone-width column. Design for 375–430px wide.
Links do nothing	Use `dehub.actions.openUrl(url)` for external links; mini apps cannot navigate the DeHub tab.

On your server

Problem	Fix
Token fails with an audience error	Set `audience` to your app's domain exactly, with no `https://` and no path.
Token fails with an expiry error	Tokens last one hour. Call `dehub.auth.getToken()` again; the SDK refreshes it.
Notifications are skipped as `notAdded`	Only people who added your app get notifications. Ask with `dehub.actions.addApp()`.
Notifications are skipped as `rateLimited`	One every 30 seconds and ten a day per person. Combine updates into one notification.
429 from the REST API	Wait for the `x-ratelimit-reset-*` seconds before retrying.

DeHub Blog · dehub.io home