What causes "s3_config.bucket is required" in unslothai/unsloth?

Set s3_config['bucket'] to the target S3 bucket name.

unslothai/unsloth · error · ValueError

s3_config.bucket is required

Error message

s3_config.bucket is required

What it means

ValueError raised by prepare_s3_dataset_download when s3_config.get("bucket") is falsy. The bucket name is the one mandatory field of the s3_config dict — before any client is built or any S3 call is made, the function validates its presence so a missing bucket produces a clear message rather than a cryptic ParamValidationError from boto3.

Source

Thrown at studio/backend/core/training/s3_dataset.py:166

def prepare_s3_dataset_download(
    s3_config: dict,
    dest_dir: Optional[str] = None,
    cancel_callback: Optional[Callable[[], bool]] = None,
) -> S3DatasetDownload:
    """Download supported dataset files from S3 to a local directory.

    Returns the local files plus the owned temporary directory, when one was
    created. Call ``cleanup()`` after the dataset loader has materialized data.

    Raises ``RuntimeError`` if boto3 is missing, and ``ValueError`` if the
    bucket/prefix contains no supported dataset files.
    """
    if not boto3_available():
        raise RuntimeError("S3 dataset loading requires boto3. Install it with: pip install boto3")

    bucket = s3_config.get("bucket")
    if not bucket:
        raise ValueError("s3_config.bucket is required")
    prefix = s3_config.get("prefix")

    _raise_if_cancelled(cancel_callback)
    client = _build_s3_client(s3_config)

    keys = _list_dataset_keys(client, bucket, prefix)
    _raise_if_cancelled(cancel_callback)
    if not keys:
        where = f"s3://{bucket}/{prefix}" if prefix else f"s3://{bucket}"
        raise ValueError(
            f"No supported dataset files ({', '.join(SUPPORTED_EXTENSIONS)}) "
            f"found under {where}"
        )

    _validate_single_extension_family(keys)

    owns_temp_dir = dest_dir is None
    target_dir = dest_dir or tempfile.mkdtemp(prefix = "unsloth_s3_dataset_")

View on GitHub (pinned to 203007d190)

Solutions

Set s3_config['bucket'] to the target S3 bucket name.
Validate the form/config upstream so the user is prompted for the bucket before the call.
Check for typos like 'Bucket' vs 'bucket' — the key is case-sensitive.

Example fix

// before
prepare_s3_dataset_download({"prefix": "datasets/x/"})
// after
prepare_s3_dataset_download({"bucket": "my-datasets", "prefix": "datasets/x/"})

Defensive patterns

Strategy: validation

Validate before calling

assert isinstance(s3_config, dict) and s3_config.get('bucket'), \
    "s3_config must include a non-empty 'bucket' key"

Type guard

def is_valid_s3_config(cfg: object) -> bool:
    return isinstance(cfg, dict) and isinstance(cfg.get('bucket'), str) and bool(cfg['bucket'].strip())

Try / catch

try:
    dl = prepare_s3_dataset_download(cfg)
except ValueError as e:
    if 'bucket is required' in str(e):
        cfg['bucket'] = prompt_user_for_bucket()  # re-prompt and retry

Prevention

Validate the config dict shape at the API/form boundary before it reaches training code.
Reject empty bucket fields in the UI, not in the backend download path.
Keep the key lowercase 'bucket' — the lookup is exact.

When it happens

Trigger: Calling prepare_s3_dataset_download({}) or {"prefix": "data/"} — any dict where 'bucket' is absent, None, or an empty string.

Common situations: UI form submitted with the bucket field left blank; config file/YAML with a typo'd or omitted bucket key; programmatic construction where the bucket variable is conditionally defined and ends up None.

Related errors

AI-assisted analysis of unslothai/unsloth@203007d190 (2026-08-15). Data as JSON: /api/errors/50073a69746b1ded. Report an issue: GitHub.