Error classes

QubicError and its subclasses — typed errors thrown by SDK constructors and validators.

All SDK errors extend the abstract QubicError base class. Catching at QubicError handles any SDK error. Catching at a subclass handles one specific failure.

Hierarchy

Error
└── QubicError (abstract)
    ├── InvalidIdentityError
    ├── InvalidSeedError
    ├── InvalidTxHashError
    └── InvalidBase64Error

`QubicError`

Abstract base class. Never thrown directly. All SDK errors carry these fields:

Property	Type	Description
`message`	`string`	Human-readable description of what went wrong
`code`	`string`	Machine-readable error code — matches the class name (e.g. `"InvalidIdentityError"`)
`context`	`unknown`	The value that caused the error — the string that failed validation
`name`	`string`	Same as `code`
`stack`	`string \| undefined`	Standard JS stack trace

The code and context fields let you handle errors programmatically without instanceof:

} catch (e) {
  if (e instanceof Error && e.name === "InvalidIdentityError") {
    // Safe even across bundler module boundaries
  }
}

Error reference

Class	Thrown by	Condition
`InvalidIdentityError`	`toIdentity`, `identityToPublicKey`	String is not exactly 60 uppercase characters
`InvalidSeedError`	`toSeed`, `publicKeyFromSeed`	String is not exactly 55 lowercase characters
`InvalidTxHashError`	`toTxHash`	String is not exactly 60 lowercase characters
`InvalidBase64Error`	`toBase64`	String is not valid standard base64

Catching errors

import { toIdentity, QubicError, InvalidIdentityError } from "@qubic.org/types"

try {
  const id = toIdentity(input)
} catch (e) {
  if (e instanceof InvalidIdentityError) {
    // e.context holds the original invalid string
    console.error(`Rejected identity: ${e.context}`)
    showFieldError("destination", e.message)
  } else if (e instanceof QubicError) {
    // Any other SDK error — log and surface generically
    console.error(`SDK error [${e.code}]:`, e.message)
  } else {
    throw e
  }
}

Using `error.code` without `instanceof`

Some bundlers produce multiple module instances, which breaks instanceof checks across boundaries. Use error.name (or error.code) as a string comparison instead:

} catch (e) {
  if (e instanceof Error && e.name === "InvalidSeedError") {
    return { error: "bad_seed", detail: (e as any).context }
  }
}

Both name and code are the class name as a string, so they are safe to compare across module instances.

Error classes

Hierarchy

QubicError

Error reference

Catching errors

Using error.code without instanceof

On this page

`QubicError`

Using `error.code` without `instanceof`