amruthpillai/reactive-resume · error · Error

The semantic stylesheet could not be rendered.

Error message

The semantic stylesheet could not be rendered.

What it means

Server-side counterpart of error 129. Thrown by createResumePdfFile (server adapter) when createResumePdfFileResult returns ok:false because hasSemanticErrors(resolvedInspection) was true. The resume's semantic stylesheet produced error-level diagnostics during compile/resolve. The thrown Error's `cause` holds the SemanticCssDiagnostic[] array. This entry point is used by the Node/Hono server process (e.g. server-side PDF export, print preview). Note: the server adapter does not support publicStyleProjection, only the browser one does.

Source

Thrown at packages/pdf/src/server.tsx:65

	...options
}: CreateResumePdfFileResultOptions): Promise<ResumePdfRenderResult<File>> => {
	const normalizedOptions = { ...options, data: parseResumeData(options.data) };
	const resolvedInspection = inspection ?? inspectResumePdf(normalizedOptions);
	if (hasSemanticErrors(resolvedInspection)) {
		return { ok: false, diagnostics: resolvedInspection.diagnostics };
	}

	return {
		ok: true,
		value: await renderResumePdfFile(normalizedOptions),
		diagnostics: resolvedInspection.diagnostics,
	};
};

export const createResumePdfFile = async (options: CreateResumePdfFileOptions): Promise<File> => {
	const result = await createResumePdfFileResult(options);
	if (!result.ok) {
		throw new Error("The semantic stylesheet could not be rendered.", { cause: result.diagnostics });
	}
	return result.value;
};

View on GitHub (pinned to 3a5b12e2a4)

Solutions

1. Use createResumePdfFileResult instead of createResumePdfFile to get { ok:false, diagnostics } and log/handle each error-level diagnostic in the server route.
2. Read error.cause in any catch block around createResumePdfFile to recover the diagnostics array for logging or for returning a structured error to the client.
3. Repair the offending semantic CSS in the stored resume (via the builder or a migration) based on the diagnostic messages.
4. As a temporary mitigation, ensure the resume's stylesheet.mode is 'legacy' so resolveResumeRuntime returns empty diagnostics and rendering proceeds.

Example fix

// before: server route throws, client gets a generic 500
try {
  const file = await createResumePdfFile({ data, filename });
} catch (e) {
  // e.message === 'The semantic stylesheet could not be rendered.'
}

// after: use Result API, surface diagnostics to the client
const result = await createResumePdfFileResult({ data, filename });
if (!result.ok) {
  return c.json(
    { error: 'stylesheet_diagnostics', diagnostics: result.diagnostics },
    422,
  );
}
const file = result.value;

import { inspectResumePdf, hasSemanticError } from '@reactive-resume/pdf/server';

const inspection = inspectResumePdf({ data });
if (hasSemanticErrors(inspection)) {
  // return 422 with diagnostics instead of calling createResumePdfFile
}

import type { ResumePdfRenderResult } from '@reactive-resume/pdf/semantic';
function isOk<T>(r: ResumePdfRenderResult<T>): r is Extract<ResumePdfRenderResult<T>, { ok: true }> {
  return r.ok;
}

import { createResumePdfFileResult } from '@reactive-resume/pdf/server';

const result = await createResumePdfFileResult({ data, filename });
if (!result.ok) {
  return c.json({ error: 'stylesheet_diagnostics', diagnostics: result.diagnostics }, 422);
}
const file = result.value;

When it happens

Trigger: Server-side PDF generation (e.g. an export endpoint or AI/print pipeline) calls createResumePdfFile with resume data whose semantic stylesheet has error diagnostics. inspectResumePdf runs synchronously, detects severity==='error' in diagnostics, and the Result branch returns ok:false, which the File-returning wrapper turns into a throw.

Common situations: Stored resume documents with semantic stylesheets that became invalid after a schema/template migration. Bulk/programmatic resume generation feeding in unvalidated CSS. A resume that renders fine in legacy mode but fails when its mode is 'semantic'. Server logs will show the throw but not the per-diagnostic detail unless the handler reads error.cause.

Related errors

• The semantic stylesheet could not be rendered.
• Applied semantic stylesheet cannot be projected
• Application documents must be PDF files.
• Unauthorized
• Public style projection does not match the resume render dat

AI-assisted analysis of amruthpillai/reactive-resume@3a5b12e2a4 (2026-08-12). Data as JSON: /api/errors/9284b9d9b9e10c65. Report an issue: GitHub.