HumanSignal/label-studio · error · ValueError

Can't import JSON-formatted tasks from {key}. If you're tryi

Error message

Can't import JSON-formatted tasks from {key}. If you're trying to import binary objects, perhaps you forgot to enable "Tasks" import method?

What it means

Label Studio raises this ValueError while loading storage-synced tasks from JSON when the fetched storage object cannot be parsed as JSON-formatted tasks. It signals that the file fetched from the cloud storage (S3/GCS/Azure/etc.) was not valid task JSON, and hints that the user probably intended a binary-object import instead.

Source

Thrown at label_studio/io_storages/utils.py:203

    This function uses ijson for streaming JSON array parsing to avoid loading the entire
    file into memory at once, which is critical for large files (>100k rows, >200MB).

    Supported formats:
        - Single JSON object: {"data": {...}}
        - JSON array: [{"data": {...}}, {"data": {...}}, ...]
        - JSONL (newline-delimited JSON): {"data": {...}}\n{"data": {...}}\n...

    Args:
        blob (bytes): The blob bytes to parse.
        key (str): The key of the blob. Used for error messages.

    Yields:
        StorageObject: link params for each task.
    """

    def _error_wrapper(exc: Optional[Exception] = None):
        raise ValueError(
            (
                f"Can't import JSON-formatted tasks from {key}. If you're trying to import binary objects, "
                f'perhaps you forgot to enable "Tasks" import method?'
            )
        ) from exc

    # Peek at the first non-whitespace character to determine format
    first_char = None
    for byte in blob:
        char = chr(byte)
        if not char.isspace():
            first_char = char
            break

    if first_char is None:
        _error_wrapper(ValueError('Empty or whitespace-only content'))

    if first_char == '[':

View on GitHub (pinned to 0b49e9b539)

Solutions

1. Enable the storage's import method for binary objects (or set the appropriate import_method) instead of JSON tasks import
2. Validate each JSON file in the bucket parses as a task list before syncing
3. Re-upload correct JSON task files matching Label Studio's expected import format
4. Wrap the sync call in try/except ValueError and log/skip the offending key

Example fix

// before
storage = S3Storage.objects.create(project=project, import_method='tasks')  # bucket holds images
// after
storage = S3Storage.objects.create(project=project, import_method='binary')  # treat files as objects

import json
key, raw = obj.key, obj.get_value().read()
try:
    data = json.loads(raw)
except json.JSONDecodeError:
    raise ValueError(f'{key} is not JSON; enable binary import method')
assert isinstance(data, (list, dict))

def is_task_json(raw: bytes) -> bool:
    try:
        d = json.loads(raw)
    except Exception:
        return False
    return isinstance(d, list) or (isinstance(d, dict) and 'tasks' in d)

try:
    load_tasks_json(...)
except ValueError as e:
    logger.error('Storage import failed: %s', e)
    switch_storage_import_method_to_binary(storage)

When it happens

Trigger: POST /api/storages/{type}/{id}/sync (or import from connected storage) where a JSON file in the bucket fails to parse as task JSON during load_tasks_json_lso; or the storage import method is set to treat JSON as task data when the files are actually binary objects.

Common situations: Bucket contains images/PDFs and user enabled 'Tasks' JSON import; malformed or truncated JSON files in the bucket; JSON files whose top-level structure isn't a list of tasks or a dict with a 'tasks' key; wrong import method selected for mixed-content buckets.

Related errors

• File "{key}" is not a JSON/JSONL/Parquet file. Only .json, .
• Error loading JSON from file "{key}".\nIf you're trying to i
• Prediction validation failed ({len(validation_errors)} error
• "url" is not found in request data
• "url" must be 2048 characters or fewer

AI-assisted analysis of HumanSignal/label-studio@0b49e9b539 (2026-08-29). Data as JSON: /api/errors/d3a048b7fa677e65. Report an issue: GitHub.