StartpodDocs

Events and errors

Reference for Startpod events, listener cleanup, and common error codes.

Register a listener with on(). It returns a cleanup function.

const off = startpod.on("server-ready", (port, url) => {
  console.log(port, url)
})

off()

Events

EventListener valueStatus
server-ready(port, url)Emitted when a dev server is ready.
port(port, 'open', url)Emitted when a virtual port opens.
error({ message })Reports an internal runtime error.
install-diagnostics(diagnostics)Reports cold or warm npm-install behavior.
preview-location({ route })Reports navigation from a managed relay preview.
preview-message(message)Reserved for compatibility; not emitted yet.
xdg-open(url)Accepted for compatibility; not emitted yet.
code(path)Accepted for compatibility; not emitted yet.

Common errors

CodeMeaning
ERR_SP_ALREADY_BOOTEDAnother live pod owns the page singleton.
ERR_SP_NOT_CROSS_ORIGIN_ISOLATEDThe host page does not have working COOP and COEP headers.
ERR_SP_BROWSER_SUBSTRATE_UNSUPPORTEDA required browser capability is missing.
ERR_SP_RUNTIME_ASSET_UNAVAILABLEThe framework integration did not serve a packaged runtime file.
ERR_SP_FS_FILE_TOO_LARGEA file exceeded the 1 MiB runtime limit.
ERR_SP_DEV_SERVER_ALREADY_RUNNINGThe pod already has an active dev server.
ERR_SP_PREVIEW_NOT_READYA preview request was made before a server was active.
ERR_SP_TORN_DOWNCode called a pod after teardown().

Do not parse human-readable error messages for application logic. Match the stable code prefix when you need to present a targeted recovery action.

On this page