> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jakan.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Custom exception types for the Stash GraphQL client.

Custom exception types for the Stash GraphQL client.

Stash GraphQL Client exceptions.

This module provides exception classes for Stash client operations: - StashError: Base exception for all Stash-related errors - StashGraphQLError: GraphQL query/validation errors - StashConnectionError: Network/connection errors - StashServerError: Server-side errors (500, 503, etc.) - StashIntegrationError: Data integration/transformation errors - StashSystemNotReadyError: System not ready (SETUP/NEEDS\_MIGRATION)

## Classes

### StashError

```python theme={null}
StashError(*args: Any)
```

Bases: `RuntimeError`

Base exception for Stash-related errors.

This error is raised when communication with a Stash server fails or when Stash API operations encounter errors.

### StashGraphQLError

```python theme={null}
StashGraphQLError(*args: Any)
```

Bases: `StashError`

Raised when a GraphQL query fails validation or execution.

This may be caused by: - Invalid GraphQL query syntax - Querying non-existent fields - GraphQL validation errors - Query execution errors

### StashConnectionError

```python theme={null}
StashConnectionError(*args: Any)
```

Bases: `StashError`

Raised when connection to Stash server fails.

This may be caused by: - Network connectivity issues - Invalid Stash URL - Stash server not running - Authentication failures

### StashServerError

```python theme={null}
StashServerError(*args: Any)
```

Bases: `StashError`

Raised when Stash server returns an error response.

This may be caused by: - Internal server errors (500) - Service unavailable (503) - Other server-side issues

### StashIntegrationError

```python theme={null}
StashIntegrationError(*args: Any)
```

Bases: `StashError`

Raised when data integration or transformation fails.

This may be caused by: - Invalid data format from Stash API - Type conversion errors - Missing required fields - Schema version mismatches

### StashSystemNotReadyError

```python theme={null}
StashSystemNotReadyError(*args: Any)
```

Bases: `StashError`

Raised when Stash system is not ready for operations.

This occurs when the system status is: - SETUP: Initial setup required - NEEDS\_MIGRATION: Database migration required

### StashConfigurationError

```python theme={null}
StashConfigurationError(*args: Any)
```

Bases: `StashError`

Raised when attempting to modify protected Stash configuration values.

This occurs when trying to modify critical server-side configuration that could corrupt the Stash installation, such as: - File system paths (database\_path, backup\_directory\_path, etc.) - System paths (ffmpeg\_path, ffprobe\_path, etc.)

These values should only be modified through the Stash web interface or configuration file to prevent accidental corruption.

### StashCleanupWarning

Bases: `UserWarning`

Warning emitted when Stash cleanup tracker encounters errors during cleanup.

### StashUnmappedFieldWarning

Bases: `UserWarning`

Warning emitted when a StashObject receives fields not declared in the model.

This can happen when: - The Stash server is *newer* than the Python client and returned fields that haven't been mapped yet. - The Stash server is *older* and still sends deprecated fields that the Python client no longer declares. - A schema rename occurred between server versions.

The extra data is preserved in **pydantic\_extra** and is safe to ignore — it just isn't accessible as typed attributes.

Unlike StashInput's DeprecationWarning (which signals upcoming enforcement of extra="forbid"), this warning is purely informational.

### StashBatchError

```python theme={null}
StashBatchError(message: str, batch_result: Any = None)
```

Bases: `StashError`

Raised when a batched mutation has any failures.

Contains the `batch_result` (`BatchResult`) so callers can inspect which operations succeeded and which failed, even on partial failure.

#### Attributes

##### batch\_result

```python theme={null}
batch_result = batch_result
```

### StashVersionError

```python theme={null}
StashVersionError(*args: Any)
```

Bases: `StashError`

Raised when the Stash server version is too old to be supported.

This occurs when the server's appSchema is below the minimum required by this client version (MIN\_SUPPORTED\_APP\_SCHEMA = 75, i.e. Stash v0.30.0).

### StashCapabilityError

```python theme={null}
StashCapabilityError(*args: Any)
```

Bases: `StashError`

Raised when a feature is requested that the connected server's appSchema doesn't support.

Distinct from `StashVersionError` (which fires at connect time when the server is below the absolute minimum). This error fires per-feature at use time when a capability the consumer is exercising isn't available on this particular server — e.g., assigning `scene.custom_fields` against a server below appSchema 79, or `performer.career_start` below appSchema 78.