juicedata/juicefs · error

failed to load config: %s

Error message

failed to load config: %s

What it means

newSpace (the PIKA/space object storage driver built on the AWS SDK v2) fails while loading the AWS configuration (region, credentials, retry options). config.LoadDefaultConfig aggregates config from env vars, shared config/credentials files, and explicit options; any fatal problem there aborts client construction before an S3 request is ever made.

Source

Thrown at pkg/object/space.go:69

	}
	return notSupported
}

func newSpace(endpoint, accessKey, secretKey, token string) (ObjectStorage, error) {
	if !strings.Contains(endpoint, "://") {
		endpoint = fmt.Sprintf("https://%s", endpoint)
	}
	uri, _ := url.ParseRequestURI(endpoint)
	ssl := strings.ToLower(uri.Scheme) == "https"
	hostParts := strings.Split(uri.Host, ".")
	bucket := hostParts[0]
	region := hostParts[1]
	endpoint = uri.Scheme + "://" + uri.Host[len(bucket)+1:]

	awsCfg, err := config.LoadDefaultConfig(ctx, append(defaultChecksumOpts(),
		config.WithCredentialsProvider(credentials.NewStaticCredentialsProvider(accessKey, secretKey, token)))...)
	if err != nil {
		return nil, fmt.Errorf("failed to load config: %s", err)
	}
	client := s3.NewFromConfig(awsCfg, func(options *s3.Options) {
		options.Region = region
		options.BaseEndpoint = aws.String(endpoint)
		options.EndpointOptions.DisableHTTPS = !ssl
		options.UsePathStyle = false
		options.HTTPClient = httpClient
		options.APIOptions = append(options.APIOptions, func(stack *smithymiddleware.Stack) error {
			return v4.SwapComputePayloadSHA256ForUnsignedPayloadMiddleware(stack)
		}, addS3UserAgent)
		options.RetryMaxAttempts = 1
	})
	return &space{s3client{bucket: bucket, s3: client, region: region}}, nil
}

func init() {
	Register("space", newSpace)
}

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Validate ~/.aws/config and ~/.aws/credentials syntax (aws configure list will surface parse errors).
2. Check AWS_* environment variables for invalid values (AWS_RETRY_MODE, AWS_MAX_ATTEMPTS, AWS_REGION format).
3. Since credentials are passed statically via WithCredentialsProvider, unset conflicting AWS_* env vars or pass config.WithSharedConfigProfile/WithRegion explicitly to avoid file loading interference.

Example fix

// before
awsCfg, err := config.LoadDefaultConfig(ctx, opts...)
// after (pin config explicitly, avoid env/file surprises)
awsCfg, err := config.LoadDefaultConfig(ctx, append(opts,
    config.WithRegion(region),
    config.WithCredentialsProvider(credentials.NewStaticCredentialsProvider(ak, sk, token)))...)

if _, err := ini.LoadFile(filepath.Join(home, ".aws", "config")); err != nil {
    return fmt.Errorf("invalid AWS shared config: %v", err)
}
for _, k := range []string{"AWS_RETRY_MODE", "AWS_MAX_ATTEMPTS"} {
    if v := os.Getenv(k); v != "" && !isInt(v) {
        return fmt.Errorf("invalid %s=%s", k, v)
    }
}

client, err := newSpace(ctx, ...)
if err != nil && strings.HasPrefix(err.Error(), "failed to load config") {
    // inspect ~/.aws files and AWS_* env vars for malformed values
    return err
}

When it happens

Trigger: config.LoadDefaultConfig returns an error — typically malformed shared config files (~/.aws/config, ~/.aws/credentials), invalid AWS_* env values (e.g. bad retry mode), or invalid options passed programmatically.

Common situations: Corrupted or hand-edited AWS shared credentials file; invalid AWS_RETRY_MODE or AWS_MAX_ATTEMPTS env values; unparseable profile definitions when running on a host with AWS tooling installed.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

• failed to load config: %s
• object storage: %s
• invalid hour number
• invalid unit
• cannot disable dir stats when there are still %d dir quotas:

AI-assisted analysis of juicedata/juicefs@c9a67b23e8 (2026-09-06). Data as JSON: /api/errors/7a6bf21ee4699cf2. Report an issue: GitHub.