12 / 15 · Troubleshooting

Troubleshooting

Start with the first error, rather than continuing after a failed command. Commands in these guides run from the folder containing package.json—source/ in the buyer bundle. Keep an untouched copy of the template for comparison.

Security-policy errors

SymptomLikely causeSafe next step
Preview refuses a missing manifest or changed requested HTMLThe build is incomplete, artifacts from different builds were mixed, or the requested document changed after hashing.Run npm run build, then npm run security:check. Preview checks each requested HTML digest; it does not compare edited source settings or the entire _headers file at startup. Do not remove the guard or edit hashes manually.
security:check reports stale outputCurrent integration/security settings, exported HTML or generated artifacts no longer match.Rebuild from source, run the check again and preview that matching build. Do not copy a policy from another export.
An inline script or event handler is blockedExported HTML was changed, a new handler was added outside the supported source workflow, or a host/CDN injected code.Rebuild from source. Use normal React handlers and review the actual blocked code or host transformation. Do not enable script unsafe-inline or unsafe-eval.
Kit works before the update but is blocked by CSPAn older policy is still served, the configured mode was not rebuilt, or the provider uses another required origin.Rebuild the active configuration, inspect the actual browser violation and all response CSP headers. Add only a reviewed exact HTTPS origin to the relevant additionalSources array, rebuild and retest verification/fallback. Keep the custom adapter's approval boundary.
Endpoint POST is refused by CSPThe destination changed after the build or another host policy also restricts form submission.Rebuild with the configured receiver and check form-action in every enforced CSP. Test the receiver separately; permission to submit does not establish its security.
Remote images, video or captions are blockedThe asset was introduced outside configured settings, its URL changed without rebuilding, or a separate host policy blocks it.Rebuild with the configured asset URLs, including dark variants and posters/captions. Add only a reviewed exact origin to image or media extra sources when needed; do not allow every HTTPS source.
A custom Kit font or analytics request is blockedThese optional provider additions are not allowed automatically.Review whether the service is wanted and permitted, add its exact origins to the applicable extra-source arrays, rebuild and test its behavior/disclosures. Do not broaden all Google or provider hosts.
_headers exists but production headers are absentThe host does not interpret that file, or its upload/configuration rules differ.Apply the generated production values through the host's documented server/CDN controls and inspect the actual HTTPS responses. Copying the JSON manifest does not install headers.
No HSTS header on local previewThe preview uses ordinary HTTP loopback.Expected. Test HSTS on the intended valid HTTPS host; do not force HTTPS caching on HTTP localhost.
A new policy allowance does not fix a blocked requestAnother CSP header is also enforced or a CDN still serves an older policy/HTML pair.Inspect every CSP header and the actual delivered HTML; deploy one matching build and review obsolete additional policies through the host configuration. Do not weaken the generated policy globally.

Follow HSTS and Content Security Policy. Regeneration fixes a build mismatch; production HTTPS, headers and third-party journeys still need their own checks.

Installation and terminal errors

SymptomLikely causeSafe next step
package.json not found or npm ENOENTTerminal is in the outer bundle, documentation or another folder.Open the extracted source/ folder and start the terminal there. Confirm package.json is visible.
node or npm is not recognizedNode/npm is missing or the terminal predates installation.Install a compatible Node.js version with npm, reopen the terminal and check both versions.
EBADENGINE or unsupported Node versionRuntime does not match package.json.Use Node.js 22.13+ within version 22, or Node.js 24+, and npm 10+. Node.js 24 is recommended.
PowerShell blocks npm.ps1Script execution policy blocks that wrapper.Use npm.cmd in every npm command; do not change the system execution policy.
npm ci reports network, DNS or registry timeoutRegistry download failed.Restore internet access and retry npm ci. Check your own proxy/firewall if applicable. Do not continue with an incomplete install.
npm ci says manifest and lockfile disagreeDependency entries were edited or files from different releases were mixed.Restore a matching manifest/lockfile from your backup. If you deliberately changed dependencies, review and update the lockfile using the normal npm workflow, then retest.
File access or permission errorArchive not extracted, locked file, or an unwritable location.Extract to a folder you can edit, close your own processes holding those files and retry. Avoid running as administrator as a first fix.

Preview and build errors

SymptomLikely causeSafe next step
Port 3100 is in use (EADDRINUSE)Another local process already uses the port.Stop your own running Forma dev/preview terminal with Ctrl+C. Do not stop an unrelated service to free a port.
npm run start says to run a build firstout/index.html is missing.Run npm run build, wait for success, then start the production preview.
Development shows new text but production is oldProduction preview serves the last out/ build.Stop the preview, rebuild, then run npm run start again.
Formatting check failsAn edit differs from the project's Prettier rules.Run npm run format, review the result and repeat npm run check.
TypeScript or lint fails after a content editMissing commas, quotes, fields, wrong value types or unmatched array entries.Read the reported file and line. Compare the shared settings and both translations; preserve numeric prices, action shapes and matching count/order.
Invalid CTA destination errorA malformed or unsupported action URL was entered.Use #section, /path, an absolute HTTP(S) URL or mailto:. Remove literal whitespace/backslashes; verify the real destination exists.
Yearly button opens the same URL as MonthlyNo separate annual action is configured.Set the plan's optional annualAction when your checkout has separate yearly/monthly URLs.
Documentation check says a guide is staleMarkdown was edited without regenerating HTML.Run npm run docs, then npm run docs:check.

If another application needs port 3100, the included production preview accepts a temporary PORT setting. For example, after building, in PowerShell:

$env:PORT='3110'
npm.cmd run start

Then open http://127.0.0.1:3110. Stop that preview and close the terminal when finished; the value is scoped to that terminal and its child processes. This override applies to the production preview, not the dev command's explicit port. The site's configured canonical metadata is independent of this temporary local port.

Hosting and metadata issues

A preview still shows earlier text or styling

npm run start serves the existing production export, so source edits require a successful npm run build first. After rebuilding, reload the open preview tab. Following an in-page link such as #workflow only changes the scroll position; it does not load the new page or stylesheet. If the result still looks old, close that preview tab and open http://127.0.0.1:3100 again, confirming you are using the intended local server. Clearing unrelated browser data or changing system security settings is unnecessary.

SymptomLikely causeSafe next step
Export opened from disk is unstyled or brokenApplication asset paths expect HTTP hosting.Use npm run start locally or upload the full export to a static host. Documentation HTML can be opened directly from disk.
Live page has no styles or missing JavaScript_next/ assets were omitted, directory structure changed or upload is at the wrong path.Compare against the full out/ tree and upload its contents to the intended domain root. Check failing asset URLs.
Site only appears at /out/The containing folder was uploaded instead of its contents.Place index.html and _next/ directly in the host's public document root.
Social/sitemap URLs contain 127.0.0.1, or canonical/language alternates are missingPublic site URL was absent when building.Set NEXT_PUBLIC_SITE_URL to the final HTTPS origin, rebuild and redeploy the complete output.
Social image or favicon looks oldWrong file/reference or browser/service cache.Open the deployed asset URL directly, check the file and metadata references, then refresh the relevant cache if supported.
Deployed page differs from local productionIncomplete upload, stale host cache or another document root.Verify the published directory and deployed file contents before changing code. Replace the complete export and refresh the host's cache where appropriate.
Missing URLs show the homepage with status 200Host uses a fallback rather than an error page.Use the host's documented custom-404 setting so missing pages serve 404.html with a 404 status.
Font looks different for Greek or other scriptsBundled Manrope is Latin-only.Add an appropriately licensed font with the needed glyph coverage and update localFont; test layout after replacement.

Demo versus real functionality

A kind: 'demo' action always opens demo access, independently of newsletter placement. Default demoAccess.mode: 'preview' validates name/email locally and reveals a labelled demonstration confirmation with dialogAction, supplied as a normal link to #product. It creates no account or subscription, sends nothing and saves/transmits no input. Closing resets it. Empty or spaces-only names and invalid email must not continue.

With demoAccess.mode: 'kit', the same Forma-styled popup includes a separate optional, initially unchecked marketing choice. Unchecked continues without a Kit signup request. Checked submits name/email and the permission tag to a separate configured Kit Form in the background; continuation remains independent. The link is public and is not authentication or protected access.

With enabled newsletter placement dialog, exact #newsletter actions open newsletter signup; deliberately use such a link if the header should open signup. Other normal links navigate directly. Newsletter preview is a non-collecting demonstration. kit-native shows Forma fields immediately and submits valid opted-in requests through Kit's public handler; kit embeds the provider-designed Form. A received request does not mean confirmed subscription. Endpoint mode posts to the configured compatible receiver. See Customization and Email signup and Kit.

Changing language navigates to a different static page with fresh transient state. Closing/reopening newsletter preserves its current instance unless the shared dialog opens demo access; demo access resets on close. Forma does not persist entries to browser preferences. Closing cannot cancel a sent request, unload a provider, revoke its storage or unsubscribe email. Theme/language memory remains permission-gated.

Product media and generic cards do not implement an application backend. Checkout links need a working destination; displayed prices do not generate subscriptions or payments. A real private API, authentication service or JSON receiver needs an appropriate implementation outside this static template.

Media, cards and testimonials

SymptomLikely causeSafe next step
Product or gallery image is missingPath does not match an actual public file, or export is stale./product/example.webp needs public/product/example.webp. Check filename case, rebuild and open the served asset URL.
An added card/image has a content validation errorShared and translated arrays differ, or an image has no translated alt text.Add matching entries at the same positions in site settings and both content files. Read the reported field path.
Screenshot looks letterboxedImages have different ratios; the first reserves the preview stage.Prefer matching source ratios and correct width/height values. Images contain-fit rather than stretch.
Video mode fails to buildpreview.video is absent, paths/dimensions are invalid or captions settings are incomplete.Configure a real local video/poster and positive dimensions; review the video recipe in Customization.
A video does not play or has no captionsUnsupported/incorrect media file, missing track or host MIME issue.Test playback and the direct asset URLs on the production host; use a supported codec, appropriate response type and valid WebVTT track. A missing-file HTML page is not a video.
The themed video bar is not visibleJavaScript is disabled, has not finished loading or has an error.The video keeps native controls before the enhancement and without JavaScript. Inspect the production console/network if the rest of the interactive page also fails.
Video seek/time initially shows no durationWith preload="none", media metadata may not yet be loaded.Start playback. Seeking enables once the browser has a usable duration; if it remains unavailable, inspect the actual media and host responses.
Video plays but cannot seek reliablyThe host does not serve video byte ranges correctly, or the media itself is not seekable.Check for Accept-Ranges: bytes and a valid range request returning 206 with Content-Range. Compare the same clip using the supplied npm run start helper, which supports ranges. See Build and deploy; no production application server is required.
The captions button is missingNo track is configured, or the configured WebVTT track has not loaded successfully.Configure all optional track fields together, check its direct URL/type and test after playback starts. A page translation does not translate the shared track.
Fullscreen is missing or a request does nothingThe browser lacks the standard Fullscreen API, permission was denied or an embedded preview restricts it.Continue in-page playback. Test the direct page in a supported browser; do not promise fullscreen on every device or iframe.
The phone has no volume slider or soundThe slider is intentionally hidden at 600 px and below; the supplied clip is silent.Use device sound controls for an audio-bearing replacement clip. Test mute/unmute separately; silent sample media has no audible volume to change.
Native controls appear after a video errorForma restores the browser fallback after playback/media failure.Read the translated status, fix the media URL/format/network issue and retry Play. A fallback does not make an unsupported file playable.
Playback button has no animated haloVideo is paused or the visitor prefers reduced motion.This is intentional. The small CSS effect runs only while playing and does not affect playback or control availability.
Testimonials do not rotateAutoplay is disabled, there is fewer than two quotes, focus/hover pauses, the tab is hidden, or reduced motion is enabled.Review the actual settings and browser preference; use manual arrows. Pause is intentional and one quote needs no controls.
Testimonial interval fails configuration validationintervalMs is below the five-second minimum.Use at least 5000 milliseconds; the default is 7000. Smaller values fail validation rather than silently adjusting the configuration.

See Customization for the exact central settings and Appearance for assets and ratios.

Newsletter and Kit

SymptomLikely causeSafe next step
Preview/native newsletter controls are disabledJavaScript is unavailable or has not hydrated; native mode may also have a pending/unknown request.Check the page's load/status messages. Preview collects nothing. Native Kit has a hosted fallback; do not repeatedly resubmit an unresolved request.
Preview does not confirmEmail is invalid or the required sample choice is unchecked.Correct the translated inline errors. Its confirmation is explicitly a demo and never sends email.
Wrong-language errors or statusReplacement dictionary omitted required copy, or provider copy is untranslated.Translate all dialog/newsletter values in both dictionaries, including native pending/received/error/unknown and verification labels. Edit embedded fields/provider confirmation in Kit.
Newsletter section disappearedPlacement is dialog, or mode is disabled.Use an exact #newsletter action for enabled dialog signup; kind: 'demo' opens independent demo access. Restore section placement or redirect disabled links.
Signup opens a popup instead of scrollingEnabled newsletter placement is dialog and its destination is exactly #newsletter.Expected; use section placement for an on-page form or a real external destination for direct navigation.
Unfinished signup remains after reopeningIts newsletter instance remains mounted in the shared dialog.Expected until switching that dialog to demo access, refreshing, leaving or changing language. Entries are not saved to browser storage by Forma; closing does not unsubscribe.
Embedded Kit waits behind a Load controlkitLoad: 'interaction' is selected.Choose Load signup form, or use kitLoad: 'automatic' for loading on section mount/first popup opening. Preference permission does not control this setting.
A ready button remains after fields appearAn older build or incorrect loader customization is in use.Rebuild the current source. The optional loading button disappears after the actual embedded Form renders; native mode has no Load/ready button.
Kit configuration fails validationPublic values do not match, required native metadata/fallback is absent, or a privacy URL is missing.Copy issued UID/script/share values, numeric Form/tag metadata, exact name mapping and reCAPTCHA flag into the correct slots. Never use a private API key.
Native demo and newsletter conflictThe same UID or known numeric Form ID is active for both purposes.Create/publish a separate demo-access Form; keep newsletter and demo settings distinct. Both language slots still need values.
Embedded Kit fails/times outNetwork, blocker, security policy, wrong values or unpublished changes.Check the actual Form, Retry and hosted link. For returning visitors use Continue to show the form, save/publish and retest a fresh context.
Share URL fails validationIt is relative, HTTP or malformed.Copy the full HTTPS Embed → Share URL. Native signup requires it; embedded mode alone may omit it with an empty value.
Native request reports an errorHandler loading, initialization or provider validation failed.Review the visible message and hosted fallback. Check public mappings and allowed provider resources; do not invent success or bypass verification.
Native request remains unknownThe request may still be processing or awaiting a provider step.Check provider confirmation/status before retrying. Unknown is not failure or success; repeat submission stays blocked while unresolved. Use the hosted Form deliberately if needed.
Demo access works with marketing uncheckedMarketing is optional and independent of public demo continuation.Expected: no Kit signup request should occur. This does not create an account or authenticate the visitor.
Native received message appears but email is absentRequest acceptance is separate from confirmation and delivery.Verify the correct Form/status/tag and Kit's confirmation/sender diagnostics. Enable confirmation and disable auto-confirm for double opt-in; inspect spam/provider delivery rules.
Embedded Kit accepts signup without the tagKit owns its own checkbox behavior and may allow signup or an incentive while unchecked.Configure its permission tag, and target marketing only to active/confirmed subscribers with that permission. Native newsletter's required choice does not govern embedded Forms.
A Form change is not visibleIt is unpublished, cached or uses copied metadata.Publish and allow propagation. JavaScript embeds receive provider updates; native numeric mappings/flag must be recopied after relevant changes and Forma rebuilt.
Endpoint navigates or rejects inputIt is an ordinary encoded form POST, or receiver mappings/format differ.Verify field names, server-side validation and the receiver's actual success/error/redirect response; no same-page success is invented.
Cookie withdrawal does not unsubscribeAppearance/language storage and marketing are separate.Use the actual email unsubscribe/withdrawal process; preference withdrawal only controls optional first-party memory.

Read Email signup and Kit for complete setup, copied public metadata, tests and consent-record responsibilities. The native handler uses current provider initialization/completion behavior, which may change; keep the hosted fallback and retest after provider changes. A field, local checkbox or received request alone proves neither delivery nor an immutable consent history.

Languages and translated content

SymptomLikely causeSafe next step
Changing code leaves old-language textCodes configure routes; they do not translate content.Edit the corresponding stable primary.ts or secondary.ts dictionary. Use the complete Languages recipe.
Error names a language and content. fieldA field is missing/empty, a placeholder changed or arrays differ.Read the first field path, compare both dictionaries and preserve keys, required tokens and matching order/counts.
Duplicate/invalid/default-code errorLanguage settings contain invalid tags or a default outside the pair.Use two distinct valid codes and exactly one of them as defaultCode. Keep primary/secondary slots.
Language page works in development but fails liveLanguage directory omitted or host does not serve directory indexes.Upload complete out/, including both code directories; verify direct visits and refreshes.
Old language URL still opens after code changeOld output remains in the host document root.Deploy a complete clean export; configure intended old-to-new redirects separately using the host's established settings.
Direct English URL ignores saved GreekExplicit language URLs intentionally take priority.Test remembered language at root / instead. Do not redirect a direct language URL based on a cookie.
Root does not remember the languageNo valid optional permission, unavailable/expired cookie or unconfigured saved code.Review only this site's preference settings/storage; switching still works without memory.
Price punctuation/symbol placement is wrong for the audienceLanguage formatLocale is unsuitable.Set a suitable locale in languages.ts, keep currency/numbers in siteSettings.sections.pricing, rebuild and review both pages.
Long translated labels overlapNew copy differs in length or script.Shorten appropriate UI labels and review the actual responsive layout/font. Test both themes and direction; do not hide necessary controls.

For missing glyphs or inconsistent typography, inspect the actual font coverage. Bundled Manrope is Latin-only; system fallbacks vary. Right-to-left configuration supplies direction rules, but your translated content still needs responsive and mixed-script review.

Footer navigation can move complete links onto additional rows when space is tight. That is expected responsive behaviour. If your translated labels become crowded or words split awkwardly, keep the copy concise and inspect the current built layout and font before changing styles. Do not insert forced line breaks to fit one screen width; see Appearance.

An unknown language URL is a missing page; Forma does not guess a translation for it. The shared exported 404 uses the configured default language. Verify your host serves it with a 404 status rather than silently displaying the homepage.

Cookies and preference storage

SymptomLikely causeSafe next step
Light or Dark works but is not kept after reloadAppearance storage was declined, no valid permission exists, or the browser blocks persistence.Open Cookie preferences in the footer and allow preferences if you want persistence. Review only this test site's cookie/local-storage permissions. The current-page theme controls remain usable without permission.
The banner returns on every visitThe decision cookie is blocked or cleared by the browser, or its configured name/version changed.Test a normal browser profile, check the intended settings in src/config/cookies.ts, and verify the cookie on your own origin. Do not promise persistence when the visitor's browser blocks it.
An old saved theme disappeared after upgradingVersion 1.2.0 needs a valid new allow decision instead of assuming old storage means consent.Explain the new choice to visitors. Allow appearance storage and choose the preferred theme again. Do not restore unconditional local-storage reads.
No preference banner appearsThe manager is disabled or the visitor already has a valid current-version decision.Check enabled and the intended decision version. A valid choice hides the banner; with the manager enabled, the footer preference button remains available. Test a fresh browser profile when checking the initial banner.
The footer preference button is missingThe manager is disabled or the footer/button markup was removed during customization.Check enabled in src/config/cookies.ts and preserve CookieSettingsButton in the footer. A saved decision alone does not hide this button; visitors need it to change or withdraw their choice.
The privacy-policy link does not appearIt is intentionally unset in the generic template.Set privacyPolicyHref to your real policy destination in src/config/cookies.ts, rebuild and verify the link. Forma does not create that page for you.
An added tracker loads before permissionThe manager controls Forma's optional theme/language storage.Implement and test that service's own loading/withdrawal rules; changing a label does not block trackers.
Production still shows old preference wordingSource was edited after the last build, or the deployed assets are stale.Rebuild, upload the complete output and check the intended host/cache before changing logic.

For configuration, inventory, expiry and withdrawal checks, see Cookies and preferences. Never clear unrelated browser data or change another website's storage to troubleshoot this template.

Version 1.3.0 uses decision version 2 because it adds optional language memory. A v1 allow value is not a grant for the new purpose. The banner asks again and cleanup is attempted; this is intentional. Withdrawal attempts to remove forma.theme and forma-language, while the explicit URL continues to determine page language. Blocked access can prevent physical cleanup or saving the latest decision.

Request useful help

If the issue remains, see Support. Include the Forma release, Node/npm versions, operating system, command or feature, first relevant error and a small reproduction. Check whether it occurs in an unmodified copy.

Do not send passwords, API keys, tokens, private environment files, VAT/tax details, customer data or full system logs. A short redacted error excerpt or a cropped screenshot is usually more useful than an entire project archive.