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.
On this page
Security-policy errors
| Symptom | Likely cause | Safe next step |
|---|---|---|
| Preview refuses a missing manifest or changed requested HTML | The 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 output | Current 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 blocked | Exported 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 CSP | An 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 CSP | The 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 blocked | The 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 blocked | These 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 absent | The 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 preview | The 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 request | Another 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
| Symptom | Likely cause | Safe next step |
|---|---|---|
package.json not found or npm ENOENT | Terminal 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 recognized | Node/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 version | Runtime 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.ps1 | Script 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 timeout | Registry 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 disagree | Dependency 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 error | Archive 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
| Symptom | Likely cause | Safe 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 first | out/index.html is missing. | Run npm run build, wait for success, then start the production preview. |
| Development shows new text but production is old | Production preview serves the last out/ build. | Stop the preview, rebuild, then run npm run start again. |
| Formatting check fails | An 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 edit | Missing 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 error | A 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 Monthly | No 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 stale | Markdown 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.
| Symptom | Likely cause | Safe next step |
|---|---|---|
| Export opened from disk is unstyled or broken | Application 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 missing | Public 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 old | Wrong 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 production | Incomplete 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 200 | Host 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 scripts | Bundled 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
| Symptom | Likely cause | Safe next step |
|---|---|---|
| Product or gallery image is missing | Path 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 error | Shared 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 letterboxed | Images 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 build | preview.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 captions | Unsupported/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 visible | JavaScript 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 duration | With 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 reliably | The 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 missing | No 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 nothing | The 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 sound | The 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 error | Forma 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 halo | Video 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 rotate | Autoplay 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 validation | intervalMs 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
| Symptom | Likely cause | Safe next step |
|---|---|---|
| Preview/native newsletter controls are disabled | JavaScript 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 confirm | Email 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 status | Replacement 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 disappeared | Placement 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 scrolling | Enabled 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 reopening | Its 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 control | kitLoad: '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 appear | An 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 validation | Public 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 conflict | The 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 out | Network, 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 validation | It 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 error | Handler 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 unknown | The 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 unchecked | Marketing 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 absent | Request 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 tag | Kit 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 visible | It 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 input | It 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 unsubscribe | Appearance/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
| Symptom | Likely cause | Safe next step |
|---|---|---|
Changing code leaves old-language text | Codes 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. field | A 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 error | Language 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 live | Language 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 change | Old 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 Greek | Explicit 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 language | No 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 audience | Language 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 overlap | New 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
| Symptom | Likely cause | Safe next step |
|---|---|---|
| Light or Dark works but is not kept after reload | Appearance 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 visit | The 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 upgrading | Version 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 appears | The 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 missing | The 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 appear | It 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 permission | The 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 wording | Source 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.