Skip to main content
If you encounter issues while using Retype, this guide covers the most common problems and how to resolve them.
Ensure your Retype Pro key is licensed for the same url that is set in your project retype.yml.

​
Common issues

If you see a Website Configuration Error on your published site, your Retype Pro key is not valid for the url configured in retype.yml.Check the following:
  • Your project has a url set in retype.yml.
  • The url value matches the domain your Retype Pro key is licensed for.
  • The config.js and retype.css files in the build output have not been modified.
Common scenarios that trigger this error:
  1. The site is hosted but url is not set in retype.yml.
  2. The url is set to a domain not covered by your Pro key.
  3. A build output file (config.js or retype.css) has been manually edited.
If you are confident your key and url are correct, contact hello@retype.com.
The following error indicates that the url in your project configuration does not match the domain your Retype Pro key is licensed for:
ERROR: The specified secret is not valid for the "url" config host: "example.com".
Steps to resolve:
  1. Open retype.yml and check the url value.
  2. Confirm the domain matches exactly what is listed in your Pro license.
  3. If you are using a free Community Key, verify that your site is hosted on GitHub Pages.
If the issue persists, contact hello@retype.com.
If retype build exits with an error or generates an empty output directory:
  • Confirm Retype is installed correctly by running retype --version.
  • Check that your retype.yml is valid YAML — indentation errors are common.
  • Look for error messages in the terminal output; Retype usually identifies the file and line causing the issue.
  • Ensure all files referenced in retype.yml (such as custom logos or favicons) exist at the specified paths.
By default, Retype starts a local server on port 5000. If that port is already in use, you will see a connection error.Specify a different port with the --port flag:
retype start --port 5001
Or set a default port in retype.yml:
server:
  port: 5001
If a page exists on disk but does not appear in the site:
  • Confirm the file has a .md extension.
  • Check that the file is not inside a folder that starts with . or _ — Retype ignores these by default.
  • If you use a nav configuration in retype.yml, verify the page is included in the navigation tree.
  • If the page has visibility: private or visibility: protected in its frontmatter, it will not appear in the public navigation.
If theme variable changes in retype.yml are not reflected on your site:
  • Confirm you have a valid Retype Pro license or have set start.pro: true.
  • Stop and restart retype start — the dev server may need a full restart to pick up retype.yml changes.
  • Check that variable names use kebab-case and match the documented names exactly.
  • Do not include the -- CSS prefix in retype.yml values.
See the Themes guide for more detail.
If the retype-action.yml workflow does not trigger or fails:
  • Verify the workflow file is in .github/workflows/ at the root of the repository.
  • Confirm the branch name in the workflow matches your repository’s default branch (main, master, etc.).
  • Check that the job has permissions: contents: write — this is required to create and push to the retype branch.
  • Review the Actions tab in your GitHub repository for detailed error logs.
See the GitHub Actions guide for setup instructions.
Retype only generates an RSS feed when the project has a /blog/ folder containing at least one valid blog post.
  • Ensure blog post filenames use the YYYY-MM-DD-title.md format, or that each post has a date property in its frontmatter.
  • Confirm the /blog/ folder is not excluded from the build.
See the Blogging guide for setup instructions.

​
Getting help

If none of the above resolves your issue: