Troubleshooting

Use this when CI, DSW, render previews, release assets, or audits fail.

DSW Stack Will Not Start

Symptoms:

  • make start-ci-dsw fails

  • Docker reports port conflicts

  • DSW API is unavailable at localhost:3000

Actions:

make ci-dsw-logs
make stop-ci-dsw

Use alternate ports locally:

export DSW_CI_API_PORT=3100
export DSW_CI_MINIO_PORT=9100
export DSW_API_URL=http://localhost:3100/wizard-api
make start-ci-dsw

Metamodel Is Unsupported

Symptoms:

  • discover-upstream-compat fails

  • CI says a template metamodelVersion is not covered

  • scheduled CI opens or updates an automation/dsw-compat-probe-* pull request

Actions:

  1. Read the CI summary.

  2. Open the generated compatibility probe PR if one exists.

  3. Confirm the PR copied the intended previous DSW/TDK runtime into config/dsw-compat.yml and the intended pinned KM fixture assignment into config/regression-evidence.yml.

  4. Let CI run full regression and strict preview evidence for the candidate. If it fails, check the official DSW metamodel notes linked in the summary, then update the DSW server image, matching TDK version, KM assignment, or compatibility code.

  5. Run make sync-dsw-runtime-matrix after any manual config edit.

Do not merge a probe only because the version number looks plausible. The probe is useful because CI tests the assumption.

Existing release assets are not deleted by this failure. The new upstream tag is blocked until a runtime is proven, while already-supported metamodel ranges can continue refreshing.

Translation Audit Fails

Symptoms:

  • raw Jinja appears in a translation.md

  • a translation block is malformed

  • a sentence is split by branch logic

Actions:

  1. Open the exact file from the audit message.

  2. If the Markdown block is broken, regenerate the tree.

  3. If the source unit is structurally bad, fix transform/export logic instead of hand-editing generated Markdown.

  4. Re-run:

    make audit-translation-tree

Sync or Output Audit Fails

Symptoms:

  • missing placeholder

  • new placeholder introduced

  • executable Jinja or HTML structure changed

  • static asset drift

Actions:

  1. Check the failing translation.md.

  2. Restore required placeholders such as {name}.

  3. Avoid writing raw Jinja in translations.

  4. Run:

    make sync-translation-tree
make audit-translated-template

Render Preview Fails

Symptoms:

  • PDF is missing

  • failed.json appears under outputs/project-render/...

  • DSW document worker errors

Actions:

  1. Inspect failed.json.

  2. Inspect outputs/ci-dsw/.

  3. Confirm template metamodelVersion matches the DSW runtime.

  4. Confirm the Knowledge Model bundle and project fixture are compatible.

  5. Re-run with a clean DSW stack.

Release Upload Fails

Symptoms:

  • Publish ... release assets step fails

  • gh release view says not a git repository

  • Release.tag_name already exists

  • gh release upload --clobber fails

Actions:

  1. Confirm workflow commands pass --repo "$GITHUB_REPOSITORY" to gh release.

  2. Confirm workflow has permissions: contents: write.

  3. Confirm release assets were staged under outputs/release-assets/....

  4. If Release.tag_name already exists appears, confirm the workflow template contains the create-then-edit fallback. This handles the case where the Git tag already exists or GitHub release APIs are briefly inconsistent.

  5. If GitHub immutable releases are enabled, --clobber cannot overwrite assets. Disable immutability for these CI download-bucket releases or switch to run-id-specific release tags.

Scheduled Workflows Do Not Run Where Expected

GitHub scheduled workflows run from the repository default branch. Do not assume a schedule declared only on a non-default version branch will run there.

Use branch push, workflow_dispatch, or a default-branch control workflow when you need to refresh version branches.

Release Asset Looks Stale

Remember:

  • release assets are refreshed only by successful scheduled runs, manual workflow_dispatch runs, and master pushes

  • release Git tags are stable version labels and are not moved during refresh

  • provenance is recorded in release notes, checksums, and workflow run metadata

If the asset is stale:

  1. Confirm the branch CI ran after the change.

  2. Confirm the Stage ... release assets step used the expected output paths.

  3. Confirm the Publish ... release assets step used --clobber.

  4. Confirm release-notes.md records the expected producing commit and run.