FMOD Studio Bank Version Mismatch in CI Builds - Cache Cleanup and Bank Manifest Validation Fix

If your CI build succeeds but runtime audio fails with FMOD bank version mismatch warnings, the issue is usually stale artifacts or manifest drift between generated banks and integrated bank metadata.

This guide gives you a deterministic fix path to restore bank version parity before promotion.

Problem summary

Common symptoms:

CI logs show bank load warnings about version mismatch
one environment plays audio correctly while another is silent
freshly generated banks still fail in packaged build
mismatch appears after branch merge, FMOD package bump, or cache restore

Typical impact:

inconsistent audio behavior across QA lanes
release confidence drops because bank identity is ambiguous

Root causes

Stale bank cache reuse
CI restores old bank outputs that no longer match current project metadata.
Manifest drift
Generated bank content changed, but manifest or expected hash snapshot was not updated in integration path.
Wrong load order in build pipeline
Runtime tries to load banks before correct generated bank set is staged.
Cross-branch bank path confusion
Multiple bank folders exist and CI picks the wrong target path.

Fix steps

Step 1 - Reset bank cache and stage directory

Before regenerating:

Clear CI cache keys related to FMOD bank outputs.
Delete staged bank folders in workspace and build output path.
Ensure only one canonical bank output directory is configured.

Do this once per failing branch to remove stale identity noise.

Step 2 - Regenerate banks from one pinned FMOD project state

Build banks from a clean checkout.
Confirm FMOD Studio project version and integration package version match your expected pair.
Export banks to the canonical path used by the game build job.

Avoid mixed local exports and CI exports in the same promotion cycle.

Step 3 - Validate bank manifest identity

Create or refresh a small manifest contract:

bank filename
size
hash
generated timestamp
source commit SHA

Fail CI if any required bank hash differs from manifest without an intentional update.

Step 4 - Verify runtime load path and order

Confirm runtime initialization points to the same bank path used in CI artifact staging.
Load banks only after FMOD initialization completes.
Log loaded bank names and manifest hash at startup in development and release builds.

This removes ambiguity when QA compares machine pools.

Step 5 - Add promotion gate checks

Require these checks before shipping:

manifest and bank artifact hashes match
no version mismatch warnings in startup logs
one smoke scene with expected music and SFX passes
bank manifest attached to release evidence packet

Verification checklist

[ ] CI cache and staged bank directories were cleared before regeneration.
[ ] Bank outputs were regenerated from a pinned FMOD project and commit state.
[ ] Manifest hash and artifact hash match for all required banks.
[ ] Runtime logs show successful bank load with no mismatch warnings.
[ ] Smoke test confirms expected audio playback in packaged build.

Alternative fixes

If mismatch occurs only on one CI runner, compare cache key scope and file restore path for that runner.
If mismatch appears after FMOD integration package update, rebuild banks and revalidate load order with updated plugin bootstrap.
If editor is green but packaged build fails, inspect build script copy step for wrong bank folder selection.

Prevention tips

Keep a versioned bank manifest artifact per release candidate.
Tie bank generation and game build to the same commit SHA.
Use one canonical bank path and document it in CI config.
Re-run bank manifest validation after FMOD Studio or integration package bumps.

FAQ

Why does this happen after successful bank build

Successful build does not guarantee runtime parity. If cached banks or manifest metadata are stale, runtime can still load mismatched identities.

Should we keep FMOD bank caches in CI

Yes, but only with strict cache-key invalidation tied to FMOD project and manifest changes.

Do we need hash checks if bank filenames are unchanged

Yes. Filename stability does not prove content identity. Hash validation catches silent drift.