Common integration pitfalls

This chapter documents errors observed in practice when integrating third-party Wakapps. For each pitfall: the observable symptom, the root cause, and the solution.

---

1. "No realm is associated with this subdomain"

Symptom: start-login returns 404 not_found.

Correct extractSubdomain function:

typescriptCopy
function extractSubdomain(hostname: string): string {
  const suffix = process.env.NEXT_PUBLIC_PLATFORM_DOMAIN_SUFFIX;
  if (suffix && hostname.endsWith(`.${suffix}`)) {
    return hostname.slice(0, -(suffix.length + 1));
  }
  const labels = hostname.split(".");
  if (labels.length <= 2) return "";
  return labels.slice(0, -2).join(".");
}
// "app.test.wakastart.app" (suffix="wakastart.app") → "app.test"
// "localhost" → ""

---

2. "Invalid client or Invalid client credentials" on callback

Symptom: The /api/auth/callback POST handler returns 401 with this Keycloak message.

Correct storage pattern:

typescriptCopy
// Store BEFORE window.location.assign()
const { keycloakUrl } = await startLogin(payload);
const parsed = new URL(keycloakUrl);
sessionStorage.setItem("login_realm",     parsed.pathname.match(/\/realms\/([^/]+)\//)?.[1] ?? "");
sessionStorage.setItem("login_client_id", parsed.searchParams.get("client_id") ?? "");
// pkce_verifier already stored right after generation
window.location.assign(keycloakUrl);

---

3. "Missing enriched token" on every API call

Symptom: The user is logged in (cookies exist, /me responds), but every proxied call to downstream services returns 401 Missing or invalid enriched token.

---

4. organization claim absent — empty dashboard

Symptom: The user logs in without error, but the dashboard has no rights and /me returns appRights: [].

Cause: The Keycloak token does not contain the organization claim required by the WakaStart auth service. Enrichment returns a minimal token with no business rights.

Solution — 3 mandatory steps:

1. Keycloak console → realm → Realm settings → General → enable "Organizations enabled"
2. Keycloak console → realm → Clients → {client_id} → Client scopes → add organization as Default
3. Run npx ts-node prisma/backfill-keycloak-orgs.ts in the WakaStart config service to create the Keycloak organizations and attach users to them.

Verification: Decode the Keycloak token after login. It must contain:

jsonCopy
{
  "organization": {
    "ACM001": {}
  }
}

---

5. sameSite: strict cookie blocks the session on return from Keycloak

Symptom: After the Keycloak redirect to /api/auth/callback, cookies are not transmitted. The handler cannot read pkce_verifier or the session cookies. The user is redirected in a loop back to login.

Cause: Cookies with sameSite: strict are not sent on a cross-site navigation (the Keycloak → your app redirect is considered cross-site).

Solution: Use sameSite: lax for all cookies in the auth flow.

typescriptCopy
cookieStore.set("keycloak_token", token, {
  httpOnly: true,
  secure: true,
  sameSite: "lax",  // ← not "strict"
  ...
});

---

6. Container Next.js build fails — EACCES on .next/cache/images

Symptom:

Error: EACCES: permission denied, mkdir '/app/.next/cache/images'

Cause: The COPY .next ./.next in the Dockerfile doesn't transfer the correct permissions to the container's non-root user.

Solution:

dockerfileCopy
# In the Wakapp Dockerfile's production stage
FROM node:22-alpine AS runner
RUN addgroup --system --gid 1001 nodejs && \
    adduser --system --uid 1001 nextjs

WORKDIR /app
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static

# Create the image cache folder with the right permissions
RUN mkdir -p /app/.next/cache/images && chown -R nextjs:nodejs /app/.next/cache

USER nextjs

---

7. Rate limit triggered on Discovery during initial integration

Symptom: After a few quick tests, the Discovery service responds 429 to every request.

Cause: During integration, developers call start-login in a loop to debug. The 5 req/s limit is hit quickly.

Solution:

• Don't call start-login on every page refresh — cache the keycloakUrl if the user isn't logged in.
• In local integration, use a mock of the Discovery service.
• Wait for the window to expire (Retry-After) before retrying.

---

8. redirect_uri with a trailing slash

Symptom: 400 invalid_redirect_uri during the token exchange with Keycloak.

Cause: Keycloak compares the callback URI exactly (sensitive to the trailing / and to casing).

Solution: Normalize the callback URI (remove the trailing slash) and make sure the value is identical in start-login, in the callback handler, and in the Keycloak console.

typescriptCopy
const REDIRECT_URI = process.env.AUTH_CALLBACK_URL!.replace(/\/$/, ""); // Trim trailing slash

---

9. Empty appRights despite an assigned profile

Symptom: GET /me returns appRights: [] but the user does have a profile assigned, visible in the admin UI.

Causes and diagnostics:

---

10. Email with uppercase letters causes a 404 not_found on Discovery

Symptom: Lookup by email returns { users: [] } for John@Acme.com even though the user exists with john@acme.com.

Cause: Discovery normalizes emails to lowercase before searching. The email sent must already be normalized on the client side.

Solution:

typescriptCopy
// Normalize the email BEFORE calling Discovery
const normalizedEmail = email.toLowerCase().trim();
const result = await discoverByEmail(normalizedEmail);

---

Summary — Debugging checklist

When things aren't working, in order:

1. start-login returns 404 → check extractSubdomain, check network.subdomain in the DB
2. Invalid client on callback → Client authentication: OFF in Keycloak? client_id extracted from keycloakUrl?
3. wakastart_token absent → did enrich succeed? Decode the Keycloak JWT: is the organization claim present?
4. 401 Missing enriched token → is the x-enriched-token header forwarded by the proxy?
5. appRights: [] → profile assigned AND rights configured on the profile?
6. 403 → exact right matching the operation? Feature enabled in the cascade?
7. 429 → respect Retry-After, implement exponential backoff

Go further

• Common errors — HTTP: exact HTTP codes and messages
• Authentication — implementation: full flow with code
• Endpoint reference: full table of routes