Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Pratyay360/podman-ts/llms.txt

Use this file to discover all available pages before exploring further.

podman-ts defines a structured error hierarchy so you can catch specific failure modes without inspecting raw HTTP status codes or string messages. All classes are named exports from @pratyay360/podman-ts. 
import {
  PodmanError,
  APIError,
  NotFound,
  ImageNotFound,
  BuildError,
  ContainerError,
  InvalidArgument,
  StreamParseError,
} from "@pratyay360/podman-ts";

​
Error hierarchy

Error
└── PodmanError
    ├── APIError
    │   ├── NotFound
    │   └── ImageNotFound
    ├── BuildError
    ├── ContainerError
    ├── InvalidArgument
    └── StreamParseError

​
Error class reference

Base class for all podman-ts errors. Extends the built-in Error.
class PodmanError extends Error
Constructor
new PodmanError(message: string)
PropertyTypeDescription
messagestringHuman-readable error description.
namestringAlways "PodmanError".
Catch this class to handle any SDK-level error regardless of its specific type.
try {
  await client.containers.get("missing");
} catch (err) {
  if (err instanceof PodmanError) {
    console.error("SDK error:", err.message);
  }
}
Wraps HTTP error responses from the Podman service. Thrown by APIResponse.raiseForStatus() for any status >= 400 that is not a 404.
class APIError extends PodmanError
Constructor
new APIError(message: string, statusCode?: number, explanation?: string)
PropertyTypeDescription
messagestringShort error description, taken from the cause field of the response body when available.
statusCodenumber | undefinedHTTP status code returned by the service.
explanationstring | undefinedSecondary description, taken from the message field of the response body.
namestringAlways "APIError".
Methods
MethodReturnsDescription
isClientError()booleantrue when statusCode is 400–499.
isServerError()booleantrue when statusCode is 500–599.
toString()stringFormats the error as "{statusCode} Client/Server Error: {message} ({explanation})".
Thrown by APIResponse.raiseForStatus() when the Podman service returns a 404 response for a generic resource.
class NotFound extends APIError
Constructor
new NotFound(message: string, explanation?: string)
PropertyTypeDescription
statusCodenumberAlways 404.
namestringAlways "NotFound".
try {
  await client.containers.get("nonexistent");
} catch (err) {
  if (err instanceof NotFound) {
    console.log("Container does not exist");
  }
}
Thrown for 404 responses specific to image lookups, when the calling code passes ImageNotFound as the NotFoundClass argument to raiseForStatus().
class ImageNotFound extends APIError
Constructor
new ImageNotFound(message: string, explanation?: string)
PropertyTypeDescription
statusCodenumberAlways 404.
namestringAlways "ImageNotFound".
try {
  await client.images.get("nonexistent:tag");
} catch (err) {
  if (err instanceof ImageNotFound) {
    console.log("Image not found locally");
  }
}
Thrown when an image build operation fails. Includes the accumulated build log so you can display or inspect the output that led to the failure.
class BuildError extends PodmanError
Constructor
new BuildError(message: string, buildLog?: string[])
PropertyTypeDescription
messagestringShort description of the build failure.
buildLogstring[]Ordered list of build output lines captured before the failure. Defaults to [].
namestringAlways "BuildError".
try {
  await client.images.build({ path: "./app", dockerfile: "Dockerfile" });
} catch (err) {
  if (err instanceof BuildError) {
    console.error(err.buildLog.join("\n"));
  }
}
Thrown when a container exits with a non-zero status code, e.g. from containers.run().
class ContainerError extends PodmanError
Constructor
new ContainerError(message: string, exitStatus: number)
PropertyTypeDescription
messagestringHuman-readable description.
exitStatusnumberThe process exit code returned by the container.
namestringAlways "ContainerError".
try {
  await client.containers.run("alpine", { command: ["sh", "-c", "exit 1"] });
} catch (err) {
  if (err instanceof ContainerError) {
    console.error("Exit code:", err.exitStatus);
  }
}
Thrown by SDK methods when a caller passes a value that does not satisfy the method’s preconditions.
class InvalidArgument extends PodmanError
Constructor
new InvalidArgument(message: string)
PropertyTypeDescription
messagestringDescription of what was invalid.
namestringAlways "InvalidArgument".
Thrown when the SDK fails to parse a value from a streaming JSON response.
class StreamParseError extends PodmanError
Constructor
new StreamParseError(cause: unknown)
The cause is coerced to a string and embedded in the message: "Stream parse error: {cause}".
PropertyTypeDescription
messagestring"Stream parse error: {cause}"
namestringAlways "StreamParseError".

​
Catching errors in practice

import {
  NotFound,
  ImageNotFound,
  BuildError,
  ContainerError,
  APIError,
  PodmanError,
} from "@pratyay360/podman-ts";

try {
  const image = await client.images.pull("private-registry.example.com/app:latest");
} catch (err) {
  if (err instanceof ImageNotFound) {
    console.error("Image does not exist on the registry.");
  } else if (err instanceof APIError && err.isClientError()) {
    console.error(`Client error ${err.statusCode}: ${err.message}`);
  } else if (err instanceof APIError && err.isServerError()) {
    console.error(`Registry server error: ${err.toString()}`);
  } else if (err instanceof PodmanError) {
    console.error("SDK error:", err.message);
  } else {
    throw err; // re-throw unexpected errors
  }
}
Catch the most specific class first (ImageNotFound before APIError, APIError before PodmanError) because each subclass is also an instance of its parent.

Build docs developers (and LLMs) love

Get started for freeTalk to us