Troubleshooting

When something goes wrong, work out where it stops: the dashboard, the delivery API, or your site. Even if an entry is saved in the dashboard, what you see can differ because of its publish status or your site's cache.

An entry doesn't show up

1. Check that you opened the right workspace and API.
2. Check that the editor shows Saved.
3. Check the status and the publish start and end dates.
4. Call the delivery API directly and check the HTTP status.
5. If the API returns the right content, look at your site's fetching and caching.

If the list is empty, publish and save one entry first. If fetching a single entry returns 404, use the id from the delivery response in the URL, not the title.

The dashboard moved

Workspace screens live under /w/<workspace ID>. The delivery API URL is https://api.genko.me/v1/<workspace ID>/<endpoint>.

Open "Settings and plan" from the workspace menu and "Account settings" from the avatar menu. Old URLs redirect to the new ones.

The delivery API returns an error

The delivery API returns its messages in Japanese. The table quotes them as returned and explains each one.

It works locally but not in production

Check that GENKO_API_KEY is set on your hosting provider. .env.local isn't copied to production automatically. After you change environment variables, restart or redeploy as your hosting provider requires.

Don't fix this by exposing the API key to the browser. Fetch on the server. See Manage API keys.

Types are out of date, or a new API is missing

npx @genko-me/cli pull

Run this to update the types and the API list. The current CLI's client reads apis from schema.ts, so you don't need to edit it by hand when you add an API. If you limited what to sync, add the API to the selection with pull --select-apis. If older code lists APIs by hand, bring it in line with the current client configuration. pull doesn't overwrite the client.

If you narrowed the returned fields with fields, those fields aren't actually returned even though the types include them. Reference fields typed as unknown is how the generated types work. See Search and filter.

You saved, but the site is stale

If the update to a published entry already shows in the delivery API, check your site's cache and static generation. Even when a webhook succeeds, the handling after it arrives may not update the right pages.

In Webhooks, check both the notification and the revalidation or rebuild. The same goes for scheduled publishing: the API's time check and your site updating its pages are separate.

Preview doesn't work

Check that the entry is saved and that the template contains {id} and {key}. Pass the searchParams your page receives to the SDK's View. If you use your own fetching, pass draftKey to the fetch method. If you regenerate the key, the old URL stops working.

Even when the parent entry shows, references in a draft aren't expanded. See Draft preview.

List or View shows nothing

Inside List / View, name the fields you want to show by field ID, as in <ListItem id="title" /> / <ViewItem id="title" />. To see the state, place <Error template /> and <Null template /> directly under the parent. If you leave out the state components, nothing shows even on an error or empty data.

Check the field IDs and the fields in the generated schema. title and name are different IDs. If @/lib/client isn't found, align your import alias with the output location settings.

Only pagination fails

Reload the page and check again. The pagination signature expires after one hour, and you also need to reload after rotating the API key.

Check that the server's GENKO_API_KEY matches the key set on the client, and that you haven't added a custom fetch or wrapRequest. Run on the Next.js 16+ App Router with the Node.js runtime, and don't use static export. See also how pagination works.

You can't delete media, or an image doesn't change

Select the media and check which content uses it in the details panel. To delete a file that's in use, remove it from the entries that reference it and save first. "Scheduled for deletion" means the file was never attached.

After you replace a file, fetch the new URL from the delivery API. If transformation doesn't apply, also check the original image's size, whether it's animated, and the 25 MB transformation limit. See Manage media and Image transformation.

You can't invite someone to a team

Under "Settings and plan" > Members in the workspace, check the Owner role, the team's own plan, and pending invitations. Valid invitations that haven't been accepted also use up seats. Even a free team in a shared slot under a personal paid plan is limited to 3 people.

If there are several invitation emails, use the latest one and join with the same email address the invitation was sent to. See Teams and members.

A webhook doesn't arrive

From the API's Settings, open the webhook's action menu and choose "Delivery log" to see the error and the destination's response. There are no automatic retries. After you fix the receiver, select "Resend" on that log entry. "Send test" doesn't resend a past event. See Webhooks for details.

If a webhook arrives but signature verification fails, check that you use both x-genko-timestamp and x-genko-signature, and that you verify the raw body before it is parsed as JSON. The signature is an HMAC-SHA256 of timestamp.body, and a timestamp more than 300 seconds from the current time is rejected. The older scheme without a timestamp is no longer accepted. The SDK verifies this from 0.6.0.

Contact us

If you can't solve it, email [email protected] with this information.

• What you were trying to do and which action it stopped at.
• When it happened, with the time zone.
• The workspace and API, and the error status and message.
• Whether it was local or production, and how often it reproduces.

Don't send API keys, passwords, verification codes, or URLs that contain a preview key.