---
title: "Exceptions — Imports for Laravel | Roundly"
description: "Every exception with its named constructors and HTTP status — rejections, mapping, state, authorization, undo window, definition and configuration errors."
url: https://roundly-consulting.com/open-source/docs/imports-for-laravel/exceptions
language: en
---

[All packages](https://roundly-consulting.com/open-source.md)

[Imports for Laravel](https://roundly-consulting.com/open-source/docs/imports-for-laravel.md)

# Exceptions

Every exception extends ImportsException (a RuntimeException). HTTP-aware ones implement Symfony’s HttpExceptionInterface, so Laravel’s handler answers with their status and translated message ({"message": …}) — no global rendering is registered:

```php
use RoundlyConsulting\Imports\Exceptions\{ImportAlreadyRunningException, ImportsException};

try {
    $batch = Imports::for($team)->by($user)->session($id)->commit();
} catch (ImportAlreadyRunningException $e) {
    $e->runningSessionId;    // the session that holds the lock
} catch (ImportsException $e) {
    // the base class — HTTP-aware ones render as {"message": …} with their status by themselves
}
```

| Exception | Named constructors / properties | HTTP |
| --- | --- | --- |
| `ImportFileRejectedException` | ::because(RejectionReason $reason, array $context = \[\]); reason, context | 422 |
| `SheetNotFoundException` | ::named(string\|int $sheet, array $available); available | 422 |
| `InvalidMappingException` | ::withErrors(array $errors); errors keyed columns.<column> / fields.<field>; render() → {message, errors} | 422 |
| `ImportModeNotSupportedException` | ::mode(string $mode, string $importer) | 422 |
| `TooManySavedMappingsException` | ::limit(int $limit), ::tooLarge() | 422 |
| `InvalidSavedMappingException` | ::disabled(), ::invalidName(), ::unknownField(string), ::fieldTwice(string), ::empty() | 422 |
| `UnknownImporterException` | ::key(string $key) | 404 |
| `ImportNotFoundException` | ::session(), ::batch() | 404 |
| `ImportUnauthorizedException` | ::operation(string $operation) | 403 |
| `ImportStateException` | ::wrongStatus(string $status), ::stalePreview(), ::expired(), ::filePruned() | 409 |
| `UndoWindowClosedException` | ::closed() | 409 |
| `ImportAlreadyRunningException` | ::forSession(?string $runningSessionId); runningSessionId | 409 |
| `ImportRowException` | ::because(string $message) — thrown by your callbacks to fail one row | — |
| `UnscopedQueryException` | ::forModel(string $importer, string $model, string $why) | — |
| `InvalidImporterDefinitionException` | ::because(string $importer, string $rule) | — |
| `InvalidImportsConfigurationException` | ::invalidDuration(), ::invalidTable(), ::invalidValue(), ::notAnImplementation(), ::keyTypeMismatch(), ::missingTable() | — |

ImportRowException is yours to throw from a callback. UnscopedQueryException and InvalidImporterDefinitionException signal an importer that breaks a rule; InvalidImportsConfigurationException names the config key at fault.

## Show your open-source love

This package is free and MIT-licensed. If it saves you time, a one-off donation or a Patreon membership keeps it maintained, tested and documented.

[More ways to support, including crypto](https://roundly-consulting.com/support-us.md)

By donating, you agree to our [donation terms](https://roundly-consulting.com/donation-terms.md).

[Support our open source work (opens in a new tab)](https://donate.stripe.com/dRmeVe8FX5PF1Qd9pXcEw00) [Join us on Patreon (opens in a new tab)](https://www.patreon.com/cw/roundly)

## Want this built into your product?

We integrate our packages into custom Laravel and AI builds. Tell us what you're working on and we'll reply within 48 hours.

[Get a quote in 48 hours](https://roundly-consulting.com/contact.md) [Browse all packages](https://roundly-consulting.com/open-source/docs/imports-for-laravel.md)