Skip to main content
Contentstack MCP profile hub is in general availability!

Five Developer Hub gotchas that bite on day two

•
6 min read

Day one of a Developer Hub app is fine. It installs, the sidebar renders, the custom field saves. Day two is when an editor saves the config page and the API key disappears, or a sidebar shows "no results" because a request failed and nobody noticed.

None of these are exotic. They come from how the App SDK, installation data and the proxy behave, and each one is quick to fix once you know the cause. Here are the five I would check first, each with the symptom, the cause and the fix.

The short version

  • setInstallationData() replaces what is stored. It never merges.

  • appSdk.api() resolves on HTTP errors. Check res.ok.

  • Proxy mapping values are paths inside serverConfiguration, with no prefix.

  • Code is live instantly. Manifest changes wait for each installation to update.

  • A signed location only protects you if a missing token fails the check.

1. Saving the config page wipes the API key

Symptom: Everything works after install. A week later someone changes a non-secret setting, saves, and every proxied call starts returning 401.

Cause: setInstallationData() writes two buckets, configuration and serverConfiguration, and each one you send replaces the stored value. An empty object counts as a value. So this call wipes the saved key:

await installation.setInstallationData({
  configuration: { region: "eu" },
  serverConfiguration: {}, // replaces the stored secret with nothing
});

The same goes for configuration. Even the public Advanced Settings tutorial sends configuration: {} next to the secret, which is fine on a first save and destructive on any later one.

There is a second part. Every call is a separate round trip to the host, and nothing orders them. Calling setInstallationData() on every keystroke can leave an older snapshot as the last one stored.

Fix: Send serverConfiguration only when the user sets or clears a secret. Keep the form in one state object, debounce, and send the full configuration snapshot each time. Store a non-secret flag so other locations know a key exists:

const data = await installation.getInstallationData();

const payload: Record<string, unknown> = {
  configuration: { ...data.configuration, region, hasApiKey: Boolean(newKey || data.configuration.hasApiKey) },
};

if (newKey) {
  payload.serverConfiguration = { apiKey: newKey };
}

await installation.setInstallationData(payload as any);

The SDK types mark both keys as required, hence the cast. Leaving serverConfiguration out of the payload is what keeps the stored key untouched.

2. Failed requests look like empty results

Symptom: A dashboard widget shows "No entries found". The entries exist. There is no error in the console.

Cause: appSdk.api() behaves like fetch. It resolves on HTTP errors and hands you the status in a Response. A transport failure inside the host also comes back as a Response, with status 500. If your code goes straight to res.json() and reads an empty array from the error body, the UI shows "nothing found" instead of "something broke".

Fix: Check res.ok on every call and show a real error state:

const res = await appSdk.api(`${appSdk.endpoints.CMA}/v3/content_types/blog/entries`);

if (!res.ok) {
  setError(`Contentstack returned ${res.status}`);
  return;
}

const { entries } = await res.json();

While you are here, check where your 401s and 403s come from. With appSdk.api(), the permissions are the App Permissions on the UI Locations tab. Nothing is selected by default, so a missing scope shows up as an error status, not an exception.

3. The proxy sends the placeholder, not the secret

Symptom: A third-party API called through a rewrite returns 401 on every request. The key in the config page is correct.

Cause: Mappings in Advanced Settings point a name at a path inside the installation's serverConfiguration. The path is already scoped to that bucket. If you write the mapping as server_configuration.apiKey, the proxy looks for server_configuration inside serverConfiguration, finds nothing, and sends {{map.API_KEY}} upstream as literal text. The mapping saves without complaint, so the first sign is the vendor's 401.

Fix: Write the mapping value as the bare path:

{
  "mappings": {
    "API_KEY": "apiKey",
    "TRANSLATE_KEY": "integrations.translate.key"
  }
}

Then reference it in the request:

await appSdk.api("/translate", {
  method: "POST",
  headers: { Authorization: "Bearer {{map.TRANSLATE_KEY}}" },
  body: JSON.stringify({ text, target: "fr" }),
});

After saving a mapping, make one real call from an installed app with a real stored value. A saved mapping only proves it validates.

4. The new location never shows up

Symptom: You add an entry sidebar, deploy, and open the stack. The sidebar is not there. A bug fix you shipped the same day is already live everywhere.

Cause: Developer Hub versions the manifest, not your code. New code at your hosting URL reaches every installation immediately. A change to UI locations, webhooks, OAuth or hosting creates a new manifest version, and existing installations see it as an available update. They do not move to it on their own.

That split cuts both ways. A UI change ships to every customer the moment your host serves it, with no version to roll back to in Developer Hub. A new location ships to nobody until each installation updates.

Fix: Plan releases around the split. Keep a separate staging app pointing at a staging URL, so code reaches a test installation before it reaches everyone. For manifest changes, update your own installations after saving, and tell installers when an update adds something they need. Then make sure new code still works for installations on the previous manifest, since some will stay there for a while:

const sidebar = appSdk.location.SidebarWidget;

if (!sidebar) {
  // This installation has not updated to the version with the sidebar yet.
  return null;
}

5. Signed locations that sign nothing

Symptom: You set signed: true, the boilerplate verifies the token, and your backend trusts whatever the frontend sends. A request without a token gets through.

Cause: With signed: true, Contentstack appends an app-token JWT to the iframe URL. The boilerplate's useVerifyAppToken hook returns early when there is no token, so the app renders as if the check passed. The token also expires after a few minutes, so a backend that stores it as a session starts failing on its own.

Fix: Fail closed, and verify on the server where it counts:

import jwt from "jsonwebtoken";

export async function requireAppToken(token: string | null) {
  if (!token) throw new Error("Missing app-token");

  const keys = await fetch("https://app.contentstack.com/.well-known/public-keys.json").then((r) => r.json());

  return jwt.verify(token, keys["signing-key"], { algorithms: ["RS256"] });
}

Use the payload's installation_uid and stack_api_key to scope data, never IDs from the request body. Create your own session from the payload instead of reusing the token. And set signed: true on each location's meta entry, not only at the top of ui_location.

Concluding

All five share one root: the app works on install, so nobody looks again until a real editor does something you did not test. A second save on the config page, a request that fails, a mapping that never resolved, a manifest update nobody accepted, a missing token.

Test the second save, not just the first. Check res.ok. Make one real proxied call per mapping. And treat manifest changes like releases. If you are starting a new app, build your first Developer Hub app walks through all of it, with the details on installation data, the proxy and signed requests.

Frequently asked questions

  • Why did my app's API key disappear after someone saved the config page?

    setInstallationData replaces each bucket you send. Sending serverConfiguration as an empty object wipes the stored secret, so only send it when a secret is set or cleared.

  • Why does appSdk.api() not throw on a 404?

    It returns a Response for HTTP errors and turns transport failures into a Response with status 500. Check res.ok on every call.

  • Why does my third-party API return 401 through the proxy?

    Usually the mapping value is wrong. It is a path inside serverConfiguration, so drop any server_configuration prefix, or the placeholder is sent upstream as literal text.

  • Why don't existing installations show my new UI location?

    Manifest changes create a new version that installations see as an available update. Code changes go live right away, but new locations need the update.