{"record":{"id":"d3a048b7fa677e65","repo":"HumanSignal/label-studio","slug":"can-t-import-json-formatted-tasks-from-key-if-y","errorCode":null,"errorMessage":"Can't import JSON-formatted tasks from {key}. If you're trying to import binary objects, perhaps you forgot to enable \"Tasks\" import method?","messagePattern":"Can't import JSON-formatted tasks from (.+?)\\. If you're trying to import binary objects, perhaps you forgot to enable \"Tasks\" import method\\?","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"label_studio/io_storages/utils.py","lineNumber":203,"sourceCode":"\n    This function uses ijson for streaming JSON array parsing to avoid loading the entire\n    file into memory at once, which is critical for large files (>100k rows, >200MB).\n\n    Supported formats:\n        - Single JSON object: {\"data\": {...}}\n        - JSON array: [{\"data\": {...}}, {\"data\": {...}}, ...]\n        - JSONL (newline-delimited JSON): {\"data\": {...}}\\n{\"data\": {...}}\\n...\n\n    Args:\n        blob (bytes): The blob bytes to parse.\n        key (str): The key of the blob. Used for error messages.\n\n    Yields:\n        StorageObject: link params for each task.\n    \"\"\"\n\n    def _error_wrapper(exc: Optional[Exception] = None):\n        raise ValueError(\n            (\n                f\"Can't import JSON-formatted tasks from {key}. If you're trying to import binary objects, \"\n                f'perhaps you forgot to enable \"Tasks\" import method?'\n            )\n        ) from exc\n\n    # Peek at the first non-whitespace character to determine format\n    first_char = None\n    for byte in blob:\n        char = chr(byte)\n        if not char.isspace():\n            first_char = char\n            break\n\n    if first_char is None:\n        _error_wrapper(ValueError('Empty or whitespace-only content'))\n\n    if first_char == '[':","sourceCodeStart":185,"sourceCodeEnd":221,"githubUrl":"https://github.com/HumanSignal/label-studio/blob/0b49e9b53917880baf1dd85d574fe5541a9aafb2/label_studio/io_storages/utils.py#L185-L221","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Enable the storage's import method for binary objects (or set the appropriate import_method) instead of JSON tasks import","Validate each JSON file in the bucket parses as a task list before syncing","Re-upload correct JSON task files matching Label Studio's expected import format","Wrap the sync call in try/except ValueError and log/skip the offending key"],"exampleFix":"// before\nstorage = S3Storage.objects.create(project=project, import_method='tasks')  # bucket holds images\n// after\nstorage = S3Storage.objects.create(project=project, import_method='binary')  # treat files as objects","handlingStrategy":"validation","validationCode":"import json\nkey, raw = obj.key, obj.get_value().read()\ntry:\n    data = json.loads(raw)\nexcept json.JSONDecodeError:\n    raise ValueError(f'{key} is not JSON; enable binary import method')\nassert isinstance(data, (list, dict))","typeGuard":"def is_task_json(raw: bytes) -> bool:\n    try:\n        d = json.loads(raw)\n    except Exception:\n        return False\n    return isinstance(d, list) or (isinstance(d, dict) and 'tasks' in d)","tryCatchPattern":"try:\n    load_tasks_json(...)\nexcept ValueError as e:\n    logger.error('Storage import failed: %s', e)\n    switch_storage_import_method_to_binary(storage)","preventionTips":["Set the storage import method to match the actual bucket contents (binary vs tasks)","Pre-validate JSON files with a linter before uploading","Keep task JSON in dedicated buckets/prefixes separate from binary assets"],"tags":["storage","json","import","label-studio"],"backgroundTag":"invalid-json-import","analyzedSha":"0b49e9b53917880baf1dd85d574fe5541a9aafb2","analyzedAt":"2026-08-29T00:39:52.578Z","schemaVersion":2},"datasetVersion":"2026-08-29T02:17:18.158Z"}