Operations
Troubleshooting
Common upload, validation, and inference failures, with the first checks to make before rebuilding a bundle.
Common issues
| Symptom | What to check |
|---|---|
| Upload validation fails with Missing preprocess.json | Make sure the archive contains exactly one preprocess.json after extraction. A top-level folder is fine, but duplicate preprocess files can make the bundle ambiguous. |
| Upload validation fails with Missing .onnx model file | Include exactly one .onnx file in the bundle. External ONNX data files are supported for text embedding bundles when the model references them. |
| Completion returns 409 object missing | The reservation exists, but FlashML cannot find the uploaded object. PUT the tarball to upload_url first, then call complete again before expires_at. |
| Completion returns 410 expired | The presigned URL expired before the object was found. Create a new upload reservation and repeat the PUT request. |
| Inference says image file required or text input required | The model's stored modality decides the accepted input format. Image models need multipart file uploads; text models accept JSON text, form text, or a UTF-8 text file. |
| Inference fails after validation | Check that preprocess.json matches training, labels.txt order matches model outputs, and the sample input shape matches what the exported ONNX model expects. |
| Text model cannot load a tokenizer | Include tokenizer files in the bundle or set preprocess.json.tokenizer to a Hugging Face tokenizer name that FlashML can resolve during validation. |
Fast validation checklist
Archive contents
Confirm the tarball has one
.onnx file, one preprocess.json, and the expected labels or tokenizer files for the declared task.Declared task
Make sure the upload request uses the same modality and task the model was exported for, such as
image plus object_detection.Preprocessing
Match resize, crop, normalization, tokenizer, and max length settings to the transforms used during training and export.
Sample inference
After validation succeeds, run one small inference request before wiring the model into a larger app or demo.
Where to look next
Use upload status to inspect failed reservations, model bundle requirements to check required files, and errors to map HTTP status codes to next actions.