nats-io/nats-server · error
filestore max block size is %s
Error message
filestore max block size is %s
What it means
The file store rejects a FileStoreConfig.BlockSize larger than the compiled-in maxBlockSize limit. The error message includes the human-friendly maximum (friendlyBytes(maxBlockSize)). This guards against allocating file blocks the format cannot support.
Source
Thrown at server/filestore.go:424
}
func newFileStoreWithCreated(fcfg FileStoreConfig, cfg StreamConfig, created time.Time, prf, oldprf keyGen) (fs *fileStore, err error) {
return newFileStoreWithCreatedAndMode(fcfg, cfg, created, prf, oldprf, false)
}
func newFileStoreWithCreatedAndMode(fcfg FileStoreConfig, cfg StreamConfig, created time.Time, prf, oldprf keyGen, recovering bool) (fs *fileStore, err error) {
if cfg.Name == _EMPTY_ {
return nil, fmt.Errorf("name required")
}
if cfg.Storage != FileStorage {
return nil, fmt.Errorf("fileStore requires file storage type in config")
}
// Default values.
if fcfg.BlockSize == 0 {
fcfg.BlockSize = dynBlkSize(cfg.Retention, cfg.MaxBytes, prf != nil)
}
if fcfg.BlockSize > maxBlockSize {
return nil, fmt.Errorf("filestore max block size is %s", friendlyBytes(maxBlockSize))
}
if fcfg.CacheExpire == 0 {
fcfg.CacheExpire = defaultCacheBufferExpiration
}
if fcfg.SubjectStateExpire == 0 {
fcfg.SubjectStateExpire = defaultFssExpiration
}
if fcfg.SyncInterval == 0 {
fcfg.SyncInterval = defaultSyncInterval
}
dios := fcfg.srv.diskIOSemaphore()
// Check the directory
if stat, err := os.Stat(fcfg.StoreDir); os.IsNotExist(err) {
if err := os.MkdirAll(fcfg.StoreDir, defaultDirPerms); err != nil {
return nil, fmt.Errorf("could not create storage directory - %v", err)
}
} else if stat == nil || !stat.IsDir() {View on GitHub (pinned to 3a66a489d2)
Solutions
- Lower BlockSize to at most maxBlockSize (see the limit reported in the error message)
- Remove the explicit BlockSize so dynBlkSize computes a valid default
- Clamp user-provided values against maxBlockSize before building FileStoreConfig
Example fix
// before
fcfg := FileStoreConfig{BlockSize: 16 << 30}
fs, err := newFileStoreWithCreatedAndMode(fcfg, cfg, time.Now(), nil, nil, false)
// after
fcfg := FileStoreConfig{BlockSize: 8 << 20}
if fcfg.BlockSize > maxBlockSize {
fcfg.BlockSize = maxBlockSize
}
fs, err := newFileStoreWithCreatedAndMode(fcfg, cfg, time.Now(), nil, nil, false) Defensive patterns
Strategy: validation
Validate before calling
if fcfg.BlockSize > maxBlockSize {
return fmt.Errorf("BlockSize %d exceeds max %s", fcfg.BlockSize, friendlyBytes(maxBlockSize))
} Prevention
- Clamp operator-supplied BlockSize against the library max
- Prefer omitting BlockSize and letting dynBlkSize pick a default
- Watch for byte/MB unit mistakes in config files
When it happens
Trigger: Setting FileStoreConfig.BlockSize above maxBlockSize when constructing the file store (server/filestore.go:424), e.g. BlockSize of several GB or an unvalidated value from user config.
Common situations: Operator-supplied block size values passed through without clamping; unit mistakes (bytes vs MB/GB) in config files; tuning attempts that exceed the library's hard cap.
Related errors
- fileStore requires file storage type in config
- could not create hash: %v
- failed to compress block: %w
- failed to write to temporary file: %w
- short write to temporary file (%d != %d)
AI-assisted analysis of nats-io/nats-server@3a66a489d2 (2026-09-02).
Data as JSON: /api/errors/4819ecd96fb9a072.
Report an issue: GitHub.