How to fix Template literal substitution type must be literal or union in TypeScript

The compiler error points to the template literal that wraps the substitution. Identify the placeholder whose type is widening beyond literal values:

type Prefixed<T extends string> = `prefix:${T}`;
type Bad = Prefixed<string>; // ❌ Template literal substitution type must be literal or union

In this example, T can be any string, so TypeScript refuses to expand the template. The fix is to ensure T represents a finite union of literal strings instead of the open-ended string type.

Replace the placeholder with a known union so the template declares exactly which strings can appear:

type Status = "/draft" | "/published";
type StatusPath<S extends Status> = `/status${S}`;
type Draft = StatusPath<"/draft">; // ✅ emits "/status/draft"

As soon as S is a literal union, the error vanishes because the compiler can enumerate the resulting strings.

When you build unions from runtime data, lock them to literal types with as const or helper functions:

const events = ["created", "updated", "deleted"] as const;
type EventName = (typeof events)[number]; // "created" | "updated" | "deleted"
type Topic<E extends EventName> = `${E}-event`;

as const tells TypeScript to treat each string as a literal, so events[number] stays a union instead of widening to string. Without the assertion you would still see the substitution error because the placeholder would be string again.

Measured objects like Record<string, ...> or enums default to string, so derive a literal union with keyof typeof or Extract:

const routes = {
  home: "/",
  dashboard: "/dashboard",
} as const;

type RouteKey = keyof typeof routes; // "home" | "dashboard"
type RoutePath<K extends RouteKey> = `${routes[K]}?section`;

Now the placeholder is constrained to RouteKey, which is a literal union, and the template compiles without error.

Helpers such as Object.keys, Object.entries, and Array.prototype.map widen to string[]. Wrap them in a typed helper or as const so they return literal tuples:

function literalKeys<T extends readonly string[]>(...keys: T) {
  return keys;
}

const methodNames = literalKeys("getUser", "setUser");
type MethodName = typeof methodNames[number]; // "getUser" | "setUser"
type RpcCall<M extends MethodName> = `${M}Rpc`;

When the placeholder comes from MethodName, the template literal resolves cleanly.

Run the compiler and observe that the template literal error disappears:

npx tsc --noEmit

If the error is gone, IntelliSense and incremental builds will represent the literal union you intended instead of falling back to string. Keep testing with the combinations of literals you support to validate future changes.