Basker Docs

Common issues

Solutions to the most-frequently-hit problems while developing themes

This guide covers the most frequently encountered problems during theme development and deployment. Each issue includes the symptom, cause, and step-by-step fix.

Prerequisites:

  • A Basker theme project with the standard directory structure (layouts/, templates/, blocks/, assets/)
  • localstage CLI installed for local development
  • Familiarity with Liquid template syntax and JSON schema definitions

Template not rendering

Symptom: The page shows a blank screen or renders only the layout wrapper without template content.

Cause: The template filename does not follow the required naming convention. Templates should use either a base filename such as page.liquid or a named alternate such as page.landing.liquid. The first segment identifies the content type; the optional second segment identifies the variant.

Supported collection types: page, post, blog, collection, event, organization, person, season, series, venue, work.

Steps

1. Check the template filename

Verify the file is in templates/ and follows the convention:

templates/page.liquid             -- correct (base page template)
templates/page.landing.liquid     -- correct (named alternate)
templates/default-page.liquid     -- incorrect (wrong format)
templates/my_page.liquid          -- incorrect (no collection prefix)

2. Rename the file to match the convention

mv templates/my-page.liquid templates/page.liquid

3. Verify the schema is valid

Open the file and ensure it contains a valid {% schema %} tag:

{% schema %}
{
  "settings": []
}
{% endschema %}

Result: The template renders when the corresponding content type is loaded.

Verify: Open the page in the browser. The template content should appear within the layout.

Blocks not appearing

Symptom: The {% stageblocks page %} tag renders an empty <div class="content-blocks"></div> or produces no output at all.

Cause: One of the following:

  1. The template schema does not list the block names in its blocks array.
  2. The block files are missing their {% schema %} tag or have an invalid schema.
  3. The stageblocks argument does not match the content type.

Steps

1. Check the stageblocks argument

The argument must match the content type of the page. For a page document, use page:

{% stageblocks page %}

For other types, use the matching collection name:

{% stageblocks post %}
{% stageblocks event %}

2. Add block names to the template schema

Open the template file and add the block names to the blocks array:

{% schema %}
{
  "settings": [],
  "blocks": ["hero", "text-section", "image-gallery"]
}
{% endschema %}

Each entry must exactly match the name value in the corresponding block's schema.

3. Verify each block has a valid schema

Open each block file in blocks/ and confirm it has a {% schema %} tag with a name and settings array:

{% schema %}
{
  "name": "hero",
  "label": "Hero",
  "singular": "Hero",
  "plural": "Heroes",
  "settings": [
    { "name": "heading", "type": "text", "label": "Heading" }
  ]
}
{% endschema %}

4. Run the theme checker

localstage theme check

Look for block-missing-schema or template-block-missing warnings.

Result: Blocks configured in the CMS editor appear on the rendered page.

Verify: Add a block to the page in the CMS admin, publish, and reload the page in the browser.

Assets not loading (404)

Symptom: CSS, JavaScript, images, or font files return 404 errors in the browser.

Cause: One of the following:

  1. The path passed to the asset_url filter does not match the file's location in assets/.
  2. The file extension is not in the allowed list.
  3. The file is missing from the assets/ directory entirely.

Steps

1. Check the asset path

The asset_url filter expects a path relative to the assets/ directory:

{{ "styles/main.css" | asset_url | stylesheet_tag }}

This resolves to assets/styles/main.css. Verify the file exists at that exact path.

2. Verify the file extension is allowed

Only the following extensions are permitted:

css, eot, gif, ico, jpg, jpeg, js, json, png, svg, ttf, webp, woff, woff2

If your file uses a different extension, convert it to an allowed format.

3. Check for case sensitivity

File paths are case-sensitive. Logo.PNG does not match a reference to logo.png.

4. Run the theme checker

localstage theme check

Look for missing-asset-reference errors or unsupported-asset-type errors.

Result: Assets load correctly in the browser without 404 errors.

Verify: Open the browser developer tools Network tab and confirm all asset requests return 200 status codes.

Settings not updating

Symptom: Changes to config/settings_schema.json are not reflected in the CMS admin interface. Previously saved settings continue to appear.

Cause: Theme settings are read from the uploaded theme bundle. Editing settings_schema.json locally does not propagate changes to the CMS until the theme is re-uploaded.

Steps

1. Validate the settings schema locally

Ensure config/settings_schema.json is a valid JSON array of objects:

[
  {
    "name": "colours",
    "settings": [
      { "name": "primary_colour", "type": "color", "label": "Primary colour", "default": "#000000" }
    ]
  }
]

2. Run the theme checker

localstage theme check

Confirm there are no settings_schema.json-related warnings.

3. Re-upload the theme

Package the theme as a ZIP and upload it through the CMS admin interface. The new settings schema takes effect after the upload completes.

Result: The CMS admin displays the updated settings fields.

Verify: Open the theme settings panel in the CMS admin and confirm the new fields appear.

LiveReload not working

Symptom: Editing .liquid files does not trigger an automatic browser refresh during local development.

Cause: One of the following:

  1. Another process is already using port 9292 (the default LiveReload WebSocket port).
  2. The --livereload flag has been explicitly set to false.
  3. The WebSocket connection is blocked by a browser extension or network configuration.

Steps

1. Check for port conflicts

Verify no other process is using port 9292:

lsof -i :9292

If another process is listening, either stop it or specify a different port.

2. Confirm LiveReload is enabled

When the dev server starts, the terminal UI displays the LiveReload status:

  * Live reload: On

If it shows Off, ensure you are not passing --no-livereload or --livereload=false.

3. Check the browser console

Open the browser developer tools Console tab. Look for WebSocket connection errors. If the connection is refused, the port is likely blocked.

4. Restart the dev server

localstage theme dev

Result: Saving a .liquid file triggers an automatic browser refresh.

Verify: Edit any .liquid file, save it, and confirm the browser reloads automatically.

Theme upload fails

Symptom: Uploading a theme ZIP via the CMS returns an error or a list of validation failures.

Cause: The theme contains one or more validation errors. Common causes include missing required directories, invalid schema JSON, oversized assets, or disallowed file types.

Steps

1. Run the theme checker locally

localstage theme check

This runs the same validation rules as the server-side upload validator. Fix all reported errors before re-uploading.

2. Review the validation report

The checker outputs issues sorted by severity. Errors must be fixed; warnings are advisory. See the validation error reference for details on each error code.

3. Check the ZIP structure

Ensure the ZIP file contains the theme files at the root level, not nested inside an extra directory:

Correct:

theme.zip
  layouts/
  templates/
  blocks/
  assets/

Incorrect:

theme.zip
  my-theme/          <-- extra nesting
    layouts/
    templates/
    blocks/
    assets/

4. Fix all errors and re-upload

Address each error from the validation report, then re-upload the ZIP.

Result: The theme uploads successfully without validation errors.

Verify: The CMS admin shows the theme as available and active.

Rich text not rendering HTML

Symptom: Rich text fields display raw rich text source instead of rendered HTML. The output looks like {"root":{"children":[...]}} rather than formatted content.

Cause: The template accesses the raw rich text field value instead of the pre-rendered HTML variant. Basker automatically generates an _html suffixed version of every richText field that contains the rendered HTML output. The _html variant exists because rich text is exposed as rendered HTML under the _html key, while the field name itself carries a flag indicating whether the field has content.

Steps

1. Identify the field name

Check the block schema for the rich text field's name value:

{
  "name": "content",
  "type": "richText"
}

2. Use the _html variant in the template

Append _html to the field name when outputting it in the template:

Before (outputs raw JSON):

{{ block.content }}

After (outputs rendered HTML):

{{ block.content_html }}

3. Verify the output

The _html field produces safe, pre-rendered HTML that can be output directly.

Result: Rich text fields render as formatted HTML in the browser.

Verify: View the page in the browser and confirm the rich text content appears with proper formatting (headings, paragraphs, links, etc.).

Relationships showing IDs instead of data

Symptom: Relationship fields display raw record ID strings (e.g. 507f1f77bcf86cd799439011) instead of the related document's data.

Cause: The template accesses the relationship field as a scalar value instead of as a populated object. Relationship fields are automatically populated, so the related document's data is available as a nested object.

Steps

1. Identify the relationship field

Check the block schema for the relationship field:

{
  "name": "venue",
  "type": "relationship",
  "relationTo": "venues"
}

2. Access the relationship as an object

Use dot notation to access properties of the related document:

Before (outputs the ObjectId):

{{ block.venue }}

After (outputs the related document's title):

{{ block.venue.title }}

3. Check for null relationships

Wrap relationship access in a conditional to handle cases where the relationship is not set:

{% if block.venue %}
  <p>{{ block.venue.title }}</p>
{% endif %}

Result: Relationship fields display the related document's data rather than raw identifiers.

Verify: View the page and confirm the related document's fields (title, name, etc.) are rendered correctly.

Troubleshooting

Theme checker reports warnings but upload succeeds Warnings are advisory and do not block uploads. Address them to improve theme quality but they are not required for publishing.

Validation passes locally but fails on upload Ensure you are running the latest version of localstage. The local and server-side validators share the same rule set but version mismatches can cause discrepancies.

Deployment checklist

Pre-deploy validation steps before pushing a theme to production

Validation errors

Catalogue of validation errors and warnings raised during theme upload

On this page

Template not rendering
Steps
1. Check the template filename
2. Rename the file to match the convention
3. Verify the schema is valid
Blocks not appearing
Steps
1. Check the stageblocks argument
2. Add block names to the template schema
3. Verify each block has a valid schema
4. Run the theme checker
Assets not loading (404)
Steps
1. Check the asset path
2. Verify the file extension is allowed
3. Check for case sensitivity
4. Run the theme checker
Settings not updating
Steps
1. Validate the settings schema locally
2. Run the theme checker
3. Re-upload the theme
LiveReload not working
Steps
1. Check for port conflicts
2. Confirm LiveReload is enabled
3. Check the browser console
4. Restart the dev server
Theme upload fails
Steps
1. Run the theme checker locally
2. Review the validation report
3. Check the ZIP structure
4. Fix all errors and re-upload
Rich text not rendering HTML
Steps
1. Identify the field name
2. Use the _html variant in the template
3. Verify the output
Relationships showing IDs instead of data
Steps
1. Identify the relationship field
2. Access the relationship as an object
3. Check for null relationships
Troubleshooting
Related