What causes "Invalid storage config:${st}" in hcengineering/platform?

Print and inspect STORAGE_CONFIG exactly as the process sees it (echo or k8s describe) and check for trailing/empty ';'-separated segments

hcengineering/platform · error

Invalid storage config:${st}

Error message

Invalid storage config:${st}

What it means

parseStorageEnv splits the STORAGE_CONFIG environment variable on ';' and validates each entry. If an entry is empty after trim or contains no '|' separator, it throws Error('Invalid storage config:' + st). The expected per-entry format is kind(,name)?|uri|contentTypes — so this error means a syntactically malformed STORAGE_CONFIG value, not a connectivity problem.

Source

Thrown at foundations/server/packages/server-storage/src/starter.ts:46

  const storageConfig: StorageConfiguration = { default: '', storages: [] }

  const storageEnv = configEnv ?? process.env.STORAGE_CONFIG
  if (storageEnv !== undefined) {
    parseStorageEnv(storageEnv, storageConfig)
  }

  if (storageConfig.storages.length === 0 || storageConfig.default === '') {
    // 'STORAGE_CONFIG is required for complex configuration, fallback to minio config'
    addMinioFallback(storageConfig)
  }
  return storageConfig
}

export function parseStorageEnv (storageEnv: string, storageConfig: StorageConfiguration): void {
  const storages = storageEnv.split(';')
  for (const st of storages) {
    if (st.trim().length === 0 || !st.includes('|')) {
      throw new Error('Invalid storage config:' + st)
    }
    let [kindName, url] = st.split('|')
    let [kind, name] = kindName.split(',')
    if (name == null) {
      name = kind
    }
    let hasProtocol = true
    if (!url.includes('://')) {
      // No protocol, add empty one
      url = 'empty://' + url
      hasProtocol = false
    }
    const uri = new URL(url)
    const config: StorageConfig = {
      kind,
      name,
      endpoint: (hasProtocol ? uri.protocol + '//' : '') + uri.hostname, // Port should go away
      port: uri.port !== '' ? parseInt(uri.port) : undefined

View on GitHub (pinned to 63e28dc964)

Solutions

Print and inspect STORAGE_CONFIG exactly as the process sees it (echo or k8s describe) and check for trailing/empty ';'-separated segments
Ensure every entry matches kind(,name)?|uri|contentTypes with '|' separating kind and URI
Remove trailing semicolons and embedded newlines (the parser only ignores newlines in comments, not stray blanks in your value)
Use the documented example format from starter.ts as a template and restart

Example fix

// before
STORAGE_CONFIG="minio|minio:9000?accessKey=minio&secretKey=minio;"
// after
STORAGE_CONFIG="minio|minio:9000?accessKey=minio&secretKey=minio"

Defensive patterns

Strategy: validation

Validate before calling

function validateStorageEnv (storageEnv: string): void {
  const entries = storageEnv.split(';')
  for (const st of entries) {
    if (st.trim().length === 0 || !st.includes('|')) {
      throw new Error(`Invalid storage config: ${st}`)
    }
  }
}
// call before server start
validateStorageEnv(process.env.STORAGE_CONFIG ?? '')

Type guard

function isValidStorageEntry (st: string): boolean {
  return st.trim().length > 0 && st.includes('|')
}

Try / catch

try {
  parseStorageEnv(storageEnv, storageConfig)
} catch (err) {
  console.error('STORAGE_CONFIG is malformed:', (err as Error).message)
  process.exit(1)
}

Prevention

Lint STORAGE_CONFIG format in CI (each entry: kind(,name)?|uri|contentTypes)
Avoid trailing semicolons and raw newlines in env values
Use single-quoted heredocs in compose/k8s to prevent shell mangling
Log the parsed entry count at startup to confirm the config loaded fully

When it happens

Trigger: Starting a server with STORAGE_CONFIG containing a stray/empty segment (e.g. a trailing ';', a newline kept inside an entry after whitespace-only trim, or an entry like 'minio|minio:9000' missing the '|' split — most commonly a value where segments were joined without ';' or with wrong characters like ',' between entries).

Common situations: Paste errors when editing docker-compose/k8s env values; shell line continuations introducing blank segments; quoting issues where the whole variable collapsed into one malformed entry; upgrading from a single-URI config format to the multi-storage ';'-separated format without reformatting.

Related errors

AI-assisted analysis of hcengineering/platform@63e28dc964 (2026-08-29). Data as JSON: /api/errors/d08a90a2b7043b40. Report an issue: GitHub.