weaviate/weaviate · error

invalid USAGE_SHARD_CONCURRENCY: %w

Error message

invalid USAGE_SHARD_CONCURRENCY: %w

What it means

ParseCommonUsageConfig reads USAGE_SHARD_CONCURRENCY and converts it with strconv.Atoi to control how many shards are scraped concurrently. A non-integer value fails the conversion and aborts configuration with this error.

Source

Thrown at usecases/modulecomponents/usage/base_storage.go:180

	} else if config.Usage.ScrapeInterval != nil {
		scrapeInterval = config.Usage.ScrapeInterval.Get()
	}
	config.Usage.ScrapeInterval = runtime.NewDynamicValue(scrapeInterval)

	policyVersion := build.Version
	if v := os.Getenv("USAGE_POLICY_VERSION"); v != "" {
		policyVersion = v
	} else if config.Usage.PolicyVersion != nil {
		policyVersion = config.Usage.PolicyVersion.Get()
	}
	config.Usage.PolicyVersion = runtime.NewDynamicValue(policyVersion)

	// Parse shard concurrency environment variable
	shardConcurrency := DefaultShardConcurrency
	if v := os.Getenv("USAGE_SHARD_CONCURRENCY"); v != "" {
		parsed, err := strconv.Atoi(v)
		if err != nil {
			return fmt.Errorf("invalid %s: %w", "USAGE_SHARD_CONCURRENCY", err)
		}
		shardConcurrency = parsed
	} else if config.Usage.ShardConcurrency != nil {
		shardConcurrency = config.Usage.ShardConcurrency.Get()
	}
	config.Usage.ShardConcurrency = runtime.NewDynamicValue(shardConcurrency)

	// Parse verify permissions setting
	verifyPermissions := false
	if v := os.Getenv("USAGE_VERIFY_PERMISSIONS"); v != "" {
		verifyPermissions = entcfg.Enabled(v)
	} else if config.Usage.VerifyPermissions != nil {
		verifyPermissions = config.Usage.VerifyPermissions.Get()
	}
	config.Usage.VerifyPermissions = runtime.NewDynamicValue(verifyPermissions)

	return nil
}

View on GitHub (pinned to 75aa4b6d11)

Solutions

1. Set USAGE_SHARD_CONCURRENCY to a plain integer, e.g. 4.
2. Fix Helm/templating defaults so they render integers (use int, not float64).
3. Remove the env var to fall back to DefaultShardConcurrency, or configure it via config.Usage.ShardConcurrency in YAML.

Example fix

// before
USAGE_SHARD_CONCURRENCY=1.0
// after
USAGE_SHARD_CONCURRENCY=1

// Validate the env value before deploying
v := os.Getenv("USAGE_SHARD_CONCURRENCY")
if v != "" {
    if n, err := strconv.Atoi(strings.TrimSpace(v)); err != nil || n < 1 {
        panic(fmt.Sprintf("USAGE_SHARD_CONCURRENCY must be a positive integer, got %q", v))
    }
}

func isValidInt(s string) bool {
    _, err := strconv.Atoi(strings.TrimSpace(s))
    return err == nil
}

if err := usage.ParseCommonUsageConfig(cfg); err != nil {
    if strings.Contains(err.Error(), "USAGE_SHARD_CONCURRENCY") {
        log.Fatalf("fix USAGE_SHARD_CONCURRENCY (plain integer, e.g. 4): %v", err)
    }
    return err
}

When it happens

Trigger: Setting USAGE_SHARD_CONCURRENCY to a non-numeric or non-integer string — e.g. "10.0" (float), "ten", "10 shards", or an empty-with-whitespace value.

Common situations: Operators assuming it accepts a float or a percentage; templating tools (Helm) rendering a float default like 1.0; accidental quotes/whitespace in .env files.

Related errors

• invalid USAGE_SCRAPE_INTERVAL: %w
• cannot parse usage module last push date: %s: %w
• parse vector index config
• MCP write access is disabled
• no workers to add batch-jobs configured.

AI-assisted analysis of weaviate/weaviate@75aa4b6d11 (2026-09-04). Data as JSON: /api/errors/2cd43ace8e7cf5eb. Report an issue: GitHub.