Error Index#
Inspired by the Rust Compiler Error Index, this page describes the various
errors that may be presented by sphinx-theme-builder, indicating known causes
as well as potential solutions.
crash#
There is an unexpected exception raised within sphinx-theme-builder. This is
usually a symptom of an incorrect assumption/expectation or a bug in the
implementation of sphinx-theme-builder.
What you can do: It is recommended to report this issue as a crash report, on the issue tracker. This error will print a detailed traceback above it, which should be included.
nodeenv-creation-failed#
A NodeJS environment (nodeenv) could not be created, for some reason. Typically,
the reason for the failure is indicated by the output above the error. This is
an error from the underlying tooling that sphinx-theme-builder uses.
A urllib.error.HTTPError indicates that the issue is related to the network or
the availability of NodeJS release files. It may mean the node version that this
tool is trying to fetch is no longer available, for example if there is no
compatible NodeJS binary for the operating system.
What you can do: When this error is encountered, a good place to look at is the nodeenv project’s documentation and issue tracker.
non-boolean-env-variable-value#
This error is raised when the user sets the a boolean environment variable to an
invalid value. The valid values for boolean environment variables are true,
false, 1 and 0. They are case-insensitive. Providing any other value will
cause this error to be raised.
What you can do: Provide a valid value, for the environment variable involved.
can-not-use-system-node-on-windows#
This error is raised when the user tries to use the system NodeJS installation on Windows.
The underlying tooling that Sphinx Theme Builder uses (nodeenv) does not support using an existing system NodeJS installation for creating the nodeenv, so this is not permitted.
What you can do: Unset the STB_USE_SYSTEM_NODE environment variable, since
it is not possible to use the system NodeJS installation on Windows.
js-build-failed#
This error indicates that the build step using the Javascript tooling failed, which is a theme-specific issue. Typically, there is a JS error reported by the theme-specific tooling immediately above this error.
Sphinx Theme Builder executes npm run-script build for running the Javascript
tooling. When that fails, this error is raised which means that something went
wrong in the Javascript build pipeline of the theme that is being
built/packaged.
What you can do: Look into the JS error reported, since that error is what needs to be looked at (and possibly, put into a search engine).
js-install-failed#
This error indicates that the install step for the Javascript tooling failed, which is a theme-specific issue. Typically, there is a JS error reported by the theme-specific tooling immediately above this error.
Sphinx Theme Builder executes npm install for installing the Javascript
tooling that the theme declares a dependency on. When that fails, this error is
raised which means that something went wrong in the installation of the JS
dependencies of the theme that is being built/packaged.
What you can do: Look into the JS error reported, since that error is what needs to be looked at (and possibly, put into a search engine).
nodeenv-unhealthy-npm-not-found#
This error indicates that the nodeenv created for building this theme is broken,
and does not have an npm executable. Typically, this is a symptom of an
incomplete cleanup.
What you can do: Deleting the .nodeenv directory and trying again will
usually resolve this issue.
If this happens while performing multiple builds of the same theme in parallel (which is not supported at this time), this is likely caused by a race condition due to the lack of support for this mode of usage. You’ll need to ensure that no parallel builds are occurring in the same directory.
nodeenv-unhealthy-file-not-found#
This error indicates that the nodeenv created for building this theme is broken,
and does not contain a file that should have been there (the node executable).
Typically, this is a symptom of an incomplete cleanup.
What you can do: Deleting the .nodeenv directory and trying again will
usually resolve this issue.
If this happens while performing multiple builds of the same theme in parallel (which is not supported at this time), this is likely caused by a race condition due to the lack of support for this mode of usage. You’ll need to ensure that no parallel builds are occurring in the same directory.
nodeenv-unhealthy-subprocess-failure#
This error indicates that the nodeenv created for building this theme is broken, and can not be used.
Sphinx Theme Builder executes node --version using the NodeJS available in the
nodeenv to determine what version is available in the nodeenv. This error
indicates that this subprocess failed, which should never happen for a valid and
functional nodeenv.
What you can do: This is not a typical failure and may be a symptom of a
different underlying issue (incompatible architecture, broken OS libraries etc).
It may be possible to work around this by deleting the .nodeenv directory and
trying again.
nodeenv-version-mismatch#
This error indicates that the nodeenv created for building this theme does not match the declared requirements of the theme, and can not be used. Typically, this is because the declared requirement of the theme has been changed.
What you can do: Deleting the .nodeenv directory and trying again will
usually resolve this issue. If it does not, please see
Appendix: Controlling NodeJS installation. If you’re a redistributor of software (rather than a
user or theme author), the aforementioned link should provide relevant
information.
unable-to-cleanup-node-modules#
This error indicates that the node_modules folder could not be deleted.
What you can do: This is not a typical failure and will need diagnosis of why the deletion might have failed (eg: permission issues, filesystem issues).
invalid-pyproject-toml#
This error indicates that the theme does not have a valid pyproject.toml file
in the root, due to the contents of the file. Typically, this is related to the
the project table and mentions the problematic key.
What you can do: Resolve the issue as suggested by the error message. You
can find more details by looking up documentation about the [project] table
(eg: PEP 621).
pyproject-missing#
This error indicates that theme does not have a pyproject.toml file in the
root directory of the theme’s package (typically, the repository root). It is
required for using Sphinx Theme Builder.
What you can do: Create a pyproject.toml file and try again. You’ll get a
new error, which will help guide you forward.
pyproject-could-not-parse#
This error indicates that the theme do not have a valid pyproject.toml file.
It needs to be a valid TOML 1.0.0 file.
What you can do: Investigate why the file is not a valid TOML file and fix the issue.
pyproject-no-project-table#
This error indicates that the pyproject.toml file in the theme does not
contain the [project] table. That table provides required metadata and must be
specified.
What you can do: Declare your project’s metadata in the [project] table.
See PEP 621 for more details on the syntax.
pyproject-no-name-in-project-table#
This error indicates that the pyproject.toml file in the theme does not
contain the required name key in the [project] table.
What you can do: Declare your project’s name in the [project] table.
pyproject-non-canonical-name#
This error indicates that the pyproject.toml file in the theme has a name
key that is not formatted in a canonical format. This needs to be a
dashed-name-with-only-lowercase-characters.
What you can do: Fix your project’s name in the [project] table.
pyproject-invalid-version#
This error indicates that the pyproject.toml file in the theme has a version
key that is not a string.
What you can do: Fix your project’s version in the [project] table.
project-init-missing#
This error indicates that the theme’s __init__.py file could not be found.
What you can do: Move/create your theme’s importable package in the location expected. See Filesystem Layout for more details.
project-init-invalid-syntax#
This error indicates that the theme’s __init__.py file is not a valid Python
file. This file is parsed by Sphinx Theme Builder, to look up the Python version
of that file.
What you can do: Fix the file to be valid Python code.
project-double-version-declaration#
This error indicates that the theme has declared its version in both
__init__.py file and the pyproject.toml file. This is not supported.
What you can do: Declare your theme’s version in only one location.
Typically, you can do this by removing the version declaration in the
pyproject.toml file.
project-missing-dynamic-version#
This error indicates that the theme’s __init__.py file does not contain a
version declaration in the form expected by Sphinx Theme Builder.
This needs to be a top-level assignment of the form __version__ = <string>.
What you can do: Declare your theme’s version in the form expected.
project-improper-dynamic-version#
This error indicates that the pyproject.toml file in the theme has a version
key and declares that the version will be picked up from the __init__.py
file (by including version in the dynamic key).
What you can do: Declare your theme’s version in the form expected.
project-no-version-declaration#
This error indicates that Sphinx Theme Builder could not locate a version
declaration for this theme. Typically, this is because the version has not been
declared in either of the pyproject.toml or __init__.py files.
What you can do: Declare your theme’s version in the pyproject.toml file
or in the theme’s “base” __init__.py file.
project-invalid-version#
This error indicates that the theme’s declared version is not a valid Python Package version (see PEP 440 for the specification).
What you can do: Fix your theme’s version.
no-license-declared#
This error indicates that the pyproject.toml file does not declare a license,
which is not permitted when using Sphinx Theme Builder.
What you can do: Declare a license.
unsupported-dynamic-keys#
This error indicates that there are unsupported values the dynamic key in
pyproject.toml file.
What you can do: Remove the unsupported values.
no-node-version#
This error indicates that no NodeJS version was configured in the
pyproject.toml file.
What you can do: Configure the NodeJS version in the theme’s
pyproject.toml file.
node-version-mismatch#
This error indicates that the NodeJS version in the nodeenv does not match what
was configured in the pyproject.toml file.
What you can do: Typically, this is only seen when
the default NodeJS handling is overridden and is a
symptom of misconfiguration (either of sphinx-theme-builder or within the
environment). Ensure that a matching NodeJS version for the project being build
is available and, if so, delete the .nodeenv directory and try again.
If this happens while performing multiple builds of the same theme in parallel (which is not supported at this time), this is likely caused by a race condition due to the lack of support for this mode of usage. You’ll need to ensure that no parallel builds are occurring in the same directory.
missing-theme-conf#
This error indicates that the theme.conf file for the theme could not be
located.
This is typically a genuinely missing file, a symptom of a misconfiguration or
incorrect filesystem layout of the package. The misconfiguration is typically
forgetting to set theme-name in [tool.sphinx-theme-builder] in
pyproject.toml, when it does not match the PyPI package name.
What you can do: Ensure that your theme name is correct and, if so,
move/create the theme.conf file, in the expected location. If you’re creating
this file, you can find more details in
Sphinx’s theme creation documentation.
missing-javascript#
This error indicates that the Javascript file for the theme could not be located.
This is typically a genuinely missing file, a symptom of a misconfiguration or
incorrect filesystem layout of the package. The misconfiguration is typically
forgetting to set theme-name in [tool.sphinx-theme-builder] in
pyproject.toml, when it does not match the PyPI package name.
What you can do: Ensure that your theme name is correct and, if so, ensure that the Javascript file is available, in the expected location.
missing-stylesheet#
This error indicates that the CSS file for the theme could not be located.
This is typically a genuinely missing file, a symptom of a misconfiguration or
incorrect filesystem layout of the package. The misconfiguration is typically
forgetting to set theme-name in [tool.sphinx-theme-builder] in
pyproject.toml, when it does not match the PyPI package name.
What you can do: Ensure that your theme name is correct and, if so, ensure that the CSS file is available in the expected location.
could-not-read-theme-conf#
This error indicates that theme.conf could not be read.
Sphinx Theme Builder tries to read the theme.conf file of the theme being
built, parse it and read certain configuration variables declared in it. This
error is presented when that operation fails. More details are typically
available from the “context” information provided in the error message (the line
after “Could not open/parse).
What you can do: Ensure that this file can be pasted as an INI file.
theme-conf-incorrect-stylesheet#
This error indicates that the style file declared in theme.conf does not match
the stylesheet that was expected based on the theme name.
Sphinx Theme Builder enforces this consistency to make it easier to avoid collisions within derived themes and ensure that CSS file for the theme could not be located.
What you can do: Update the filename of the CSS file in theme.conf, to
match what is expected. You may also need to update your build system to
generate the file in the corresponding location.
missing-command-line-dependencies#
This error indicates that one or more of the dependencies that are needed to use
the stb command are not installed.
This is typically a symptom of doing pip install sphinx-theme-builder instead
of pip install "sphinx-theme-builder[cli]".
What you can do: Run pip install "sphinx-theme-builder[cli]" to install
the missing dependencies.
can-not-overwrite-existing-python-project#
This error is raised to prevent users from overwriting existing Python projects
with stb new, since that command does not attempt to preserve any file and is
not designed to be used on an existing Python project.
What you can do: Use a clean directory for running stb new.
no-nodeenv#
This error is raised by stb npm when the user tries to use it without creating
the nodeenv for the project.
What you can do: Run stb compile once, to create the nodeenv.
autobuild-failed#
This error is raised when sphinx-autobuild exits with an error, which is
typically caused by a fatal error or interrupt.
What you can do: Investigate why the Sphinx build failed. Typically, the output for failure above this error will provide relevant information.