Classes
StashError
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
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
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
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
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
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
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
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
StashVersionError
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
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.