What causes "location header is not found in request: ${res.url}" in keycloak/keycloak?

Inspect the full response headers (and body) to confirm whether the server emitted a `Location` at all.

keycloak/keycloak · error · Error

location header is not found in request: ${res.url}

Error message

location header is not found in request: ${res.url}

What it means

Thrown by the admin-client request `agent` when a request was made with the `returnResourceIdInLocationHeader` option (used for create operations that return the new resource's id in the `Location` response header) but the response carries no `location` header. The agent specifically needs that header to extract the id, so it aborts.

Source

Thrown at js/libs/keycloak-admin-client/src/resources/agent.ts:265

    try {
      const res = await fetchWithError(url, {
        ...requestOptions,
        headers: requestHeaders,
        method,
        ...(this.#client.timeout
          ? { signal: AbortSignal.timeout(this.#client.timeout) }
          : {}),
      });

      // now we get the response of the http request
      // if `resourceIdInLocationHeader` is true, we'll get the resourceId from the location header field
      // todo: find a better way to find the id in path, maybe some kind of pattern matching
      // for now, we simply split the last sub-path of the path returned in location header field
      if (returnResourceIdInLocationHeader) {
        const locationHeader = res.headers.get("location");

        if (typeof locationHeader !== "string") {
          throw new Error(
            `location header is not found in request: ${res.url}`,
          );
        }

        const resourceId = locationHeader.split(SLASH).pop();
        if (!resourceId) {
          // throw an error to let users know the response is not expected
          throw new Error(
            `resourceId is not found in Location header from request: ${res.url}`,
          );
        }

        // return with format {[field]: string}
        const { field } = returnResourceIdInLocationHeader;
        return { [field]: resourceId };
      }

      if (

View on GitHub (pinned to 66c7e15a37)

Solutions

Inspect the full response headers (and body) to confirm whether the server emitted a `Location` at all.
If the proxy is stripping it, configure the proxy to pass `Location` through.
If the endpoint returns the id in the body, do not set `returnResourceIdInLocationHeader` and parse the body instead.
Verify the resource genuinely supports Location-based id return for that Keycloak version.

Example fix

// before
const { id } = await kcAdminClient.clients.create({ ... });

// after: the resource returns the id in the body
const created = await kcAdminClient.someResource.create({
  ...payload,
  // returnResourceIdInLocationHeader removed / not set
});
const id = created.id;

Defensive patterns

Strategy: validation

Validate before calling

const res = await fetch(url, opts);
const location = res.headers.get('location');
if (returnResourceIdInLocationHeader && typeof location !== 'string') {
  // endpoint does not return Location; do not request id-from-location
  throw new Error(`Endpoint ${res.url} does not return a Location header; disable returnResourceIdInLocationHeader.`);
}

Type guard

const hasLocationHeader = (res: Response): boolean =>
  typeof res.headers.get('location') === 'string';

Try / catch

try {
  const { id } = await kcAdminClient.clients.create({ ...payload });
} catch (e) {
  if (e instanceof Error && e.message.startsWith('location header is not found')) {
    // resource returns id in body instead
    const created = await kcAdminClient.clients.findOne(...);
  } else throw e;
}

Prevention

Confirm the endpoint actually emits a Location header before enabling returnResourceIdInLocationHeader.
Ensure proxies pass the Location header through.
Prefer reading the id from the response body when available.

When it happens

Trigger: A `.create()`/`.post()` call where the server returned 2xx but omitted the `Location` header; a reverse proxy stripped the `Location` header; the operation does not actually return a `Location` header but the option was set; the server used a different header casing that the Headers API normalises away but the value was absent.

Common situations: Calling a non-standard endpoint that signals the new id in the body instead of the header; a proxy/load-balancer dropping `Location`; Keycloak version changed the create response shape for a resource.

Related errors

AI-assisted analysis of keycloak/keycloak@66c7e15a37 (2026-08-14). Data as JSON: /api/errors/727595d937399a4f. Report an issue: GitHub.