Troubleshoot ibek

An entity or argument is rejected

Check the type: module.Entity against the support definitions used for that run. runtime generate2 discovers definitions in the image and config folder unless --definitions was supplied, which replaces discovery. IOC schemas are specific to their support definitions: a schema from another image may accept entities the running image cannot supply. See IOC YAML and Support YAML.

For rendering failures, check parameter spelling, definition order, and the available Jinja rendering and context. Missing environment variables fail when accessed directly through env; use env.get("NAME", "default") when a default is intentional.

No schema download, or an old schema appears

A cached base schema is revalidated on every run and is also used when the fetch fails, including across fresh virtual environments. A Using cached schema ... could not revalidate it message means the download failed but the cache hid the failure. Run with a new IBEK_SCHEMA_CACHE directory to reproduce a first download; the complete recipe and cache key are in Paths and environment.

If the command reports that schema generation was skipped, check the image in values.yaml or compose.yml / compose.yaml, its explicit tag, and the repository’s ibek.ioc.schema.json release asset. A skip leaves an existing schema untouched and exits 0.

If the command exits 1 with Cannot refresh ... ioc.schema.json, the fetch failed and ibek has no cached copy for the image tag. The message includes the cause: check network access and TLS certificates, or retry after a server error or a 403 / 429 rate limit response. ibek ignores an invalid cache file and downloads the schema again.

Runtime protocols or templates are missing

Put instance .proto, .protocol, .db, and .template files directly in config/. Run runtime place-files after runtime generate2, because generation clears its output directory. Confirm the image startup script’s search paths include /epics/runtime/protocol and /epics/runtime/db as appropriate. Generated ioc.subst still needs expansion by EPICS msi before the IOC loads the database.

A vendored pattern fails its integrity check

Inspect the reported file and runtime-lock.yaml. ibek pattern restore replaces local edits from the recorded source; update records a newly selected version. Use deliberate DIRTY entries only when the divergence should be visible in version control. See Vendor runtime support.

Generation works but the IOC fails to start

Inspect st.cmd and ioc.subst under /epics/runtime, then the IOC’s output. Successful rendering validates ibek inputs; it does not prove that an EPICS command, database template, shared library, or hardware endpoint is available. For image building, deployment, and operational debugging, use the epics-containers documentation.

Changing an Ansible recipe’s version did not change the sources

The clone step reuses an existing /epics/support/<module> checkout without fetching or switching revisions. Changing version or passing ansible.sh -v only selects a revision for a new clone; the declared force_clone variable does not implement a refresh. Check the existing checkout’s Git revision and local changes. Use a fresh developer build to test the recipe from scratch, or deliberately switch the source checkout after preserving local work. See rebuilding support.

A module builds but its entities are not recognised

Compilation and support-definition registration are separate steps. Confirm the recipe directory contains a top-level *.ibek.support.yaml file and that its link under /epics/ibek-defs resolves to the intended file. A build limited to --tags do_build skips runtime registration; rerun the full module recipe, then ansible.sh ioc to regenerate the combined schema.

At runtime, check that the selected image contains that definition. Explicit runtime generate2 --definitions arguments replace automatic discovery and must include all required files. If only editor completion is wrong, refresh the schema used by the editor; the local build schema and an image’s published release schema are separate artifacts. See building support and schema caching.

A dependency’s RELEASE path is wrong

Inspect /epics/support/configure/RELEASE and the affected module’s configure/RELEASE.local link. The link should target the shared RELEASE; the dependency’s macro should point to its actual source directory. Check the dependency recipe’s macro and local_path, and build it before its consumer. Recipes do not resolve dependency order automatically.

Also inspect applicable architecture-specific configure/RELEASE.* files: upstream paths can override the container’s paths. The current role includes RELEASE.local last in the supported RELEASE files. After correcting the recipe or checkout, rerun the dependency and consumer builds rather than maintaining a separate hand-edited RELEASE configuration. See the recipe reference.