Skip to content
NaturaLife Astro Theme

Troubleshooting

Find solutions to common installation, content, image, component and deployment issues, and learn how to investigate update problems or request support.

Run commands in the folder containing the starter’s package.json. Check the Node requirement (at least 22.22.0), network/cache availability and the local archive referenced under vendor/. Use the supplied package/lock pair with npm ci; do not replace the lockfile to hide an integrity error.

Keep your source backed up before dependency changes. An authorization failure belongs to the CLI install/update workflow; ordinary theme build does not require a license-server connection.

Check JSON punctuation, required fields and the selected designed-page template. designedPage('home-5', 'HomeFive') must load HomeFive data and matching section props. When adding content, create its referenced author/category/tag IDs first. Duplicate IDs, missing references, category cycles and URL collisions are reported as errors.

Only one route can own a URL. Check the customer Astro route, ordinary document catch-all, content slug and configured injected routes before adding another owner.

Check draft, required relationships and the generated URL. Public queries and detail routes exclude drafts. Handpicked sections stay handpicked; add the record to their selection or use an appropriate query. Navigation links are separate authored data.

Section titled “An image is missing or a gallery opens the wrong file”

Imported image paths are relative to the MDX record. Registry source paths are relative to src/, while designed JSON uses logical output URLs. Verify the original exists, then rebuild. Replacing a cover does not replace separately configured galleries or backgrounds. See Images and Fonts.

Use ContentImage, ContentGallery or the documented contentImage() adapter for imported metadata. Do not copy generated thumbnails back into source. Test both root and actual subdirectory URLs.

Check the exact src/components/Name.astro filename and case. Explicit config wins over auto discovery. A direct package import deliberately uses the default; the 11 direct layout/head/content exports need a local import at the call site. Templates require explicit selection.

A wrapper that imports its own virtual component recurses: import its direct package default instead. Invalid selected files should report an error, not trigger silent fallback.

The published site is noindex or missing from the sitemap

Section titled “The published site is noindex or missing from the sitemap”

Check src/settings/site.json: the starter intentionally uses preview mode. Set genuine production SEO values, build again, then verify the deployed output. Some page types always remain excluded. A build does not certify real-host robots, canonical or HTTP 404 behavior. Follow Deployment and SEO.

Do not hand-edit kit version/hash fields. Match the core archive, dependency, lock and kit. The limited offline doctor checks this metadata; it does not certify routes, CSS, SEO, CMS behavior or build success.

CLI updates require the installation receipt created during setup. If it is missing or inconsistent, resolve that metadata problem before updating. For an interrupted transaction, use the recovery guide and retain its journal/backups if a conflict needs review. Do not overwrite later edits to force recovery.

For eligible product support, open a Dashboard ticket. Include your theme version, Node version, the failing task, the relevant error and the smallest useful example. Remove credentials, ticket values and temporary download URLs before sharing logs. Real backend development and maintenance of customized copies are separate from the supplied theme behavior.