Package Store Types
The C3 Agentic AI Platform uses different storage backends to manage packages as they move through development, collaboration, and production stages. Each storage type serves a specific purpose in the package lifecycle. Understanding these store Types helps you troubleshoot errors, work effectively with development tools, and understand how packages integrate across the C3 Agentic AI Platform.
This guide explains each store Type conceptually, shows common errors you'll encounter, and provides solutions with code examples.
Storage Types overview
The C3 Agentic AI Platform provides three main storage backends, each optimized for different stages of the package lifecycle:
| Storage Type | Purpose | Read/Write | Used By |
|---|---|---|---|
| Pkg.Store.Db | Active development | Read/Write | C3 AI Studio editor, VSCode extension, CI/CD validation |
| Pkg.Store.Zip | Distribution and production | Read-Only | Artifact Hub, production deployments |
| Pkg.Store.Java | Platform packages | Read-Only | C3 AI Platform core packages |
The C3 Agentic AI Platform automatically selects the appropriate storage backend based on what you're doing. However, understanding these types helps you troubleshoot errors and optimize your workflow.
Pkg.Store.Db - Development storage
Pkg.Store.Db stores packages in the database, providing fast access for active development. This is the primary storage backend when you're editing packages in C3 AI Studio or using the VSCode extension.
When it's used:
- Editing Type definitions in C3 AI Studio's package editor.
- Modifying packages through the C3 AI Studio UI.
- VSCode extension operations (autocomplete, go-to-definition, type checking).
- Local development environments.
Common errors
| Error | Cause | Solution |
|---|---|---|
Missing Content for file /mypackage/src/Type.c3typ in Pkg.Store.Db DEFAULT | File doesn't exist in database store (package sync issue) | Content is only available for Types in your local filesystem. To see all packages that you have content for run Pkg.Store.Db.inst().pkgs() in the C3 AI console. Sync your package with VSCE. |
Missing Pkg.File.Db: [multiple files] in Pkg.Store.Db DEFAULT | Multiple files missing from database | Check package sync or import from another store. |
If VSCode autocomplete or go-to-definition stops working, check if packages are loaded in Pkg.Store.Db using Pkg.Store.Db.inst().pkgs().
Understand writability
Pkg.Store.Db is writable, meaning you can add, modify, or delete package files. This contrasts with read-only stores like Pkg.Store.Zip, where packages are immutable.
The C3 Agentic AI Platform checks if a store is writable before allowing edit operations. If all configured stores are read-only, you'll see a "no writable store" error.
Pkg.Store.Zip - Distribution and production storage
Pkg.Store.Zip stores packages as compressed ZIP archives. This storage type is used for package distribution through Artifact Hub and for production deployments.
When it's used:
- Packages downloaded from Artifact Hub as dependencies.
- Production deployment artifacts.
- Versioned package releases.
- Immutable package snapshots.
Common errors
| Error | Cause | Solution |
|---|---|---|
Unsupported operation: doWriteEncodedContents on Pkg.Store.Zip | Zip packages are immutable by design | Use remix Types to customize (recommended) or copy to writable store if modifying the package itself is required. |
cannot read the ZIP file at https://artifacthub... | ZIP file corrupted or incomplete download | Re-download artifact, check network, clear cache |
Missing Content for file /mypackage/src/Type.c3typ in Pkg.Store.Zip | File not in ZIP archive | Verify artifact integrity or re-download from Artifact Hub |
Immutability and production safety
Pkg.Store.Zip packages are read-only by design. This immutability ensures:
- Consistent deployments across all production nodes.
- Version integrity - the package content cannot change.
- Reliable dependency management.
- Reproducible builds.
If you need to work with a dependency package, create remix Types in your package that extend the dependency's Types. This doesn't modify the original package and is the best practice for most customization scenarios.
Artifact Hub integration
Artifact Hub is the C3 Agentic AI Platform's package distribution system. When you declare a dependency in your package manifest:
- The C3 Agentic AI Platform queries Artifact Hub for the package and version
- Downloads the ZIP artifact if not already cached
- Configures Pkg.Store.Zip to serve the package
- Makes the package available as read-only
This automatic process ensures that production deployments use immutable, versioned packages from a central repository.
See also the Artifact Hub documentation.
ZIP configuration
Pkg.Store.Zip.Config controls how ZIP stores are configured, including the ZIP file URL and caching behavior.
Special purpose storage
Pkg.Store.Java - Platform packages
Pkg.Store.Java serves C3 Agentic AI Platform packages that are embedded in the C3 server JAR file. These are core C3 Agentic AI Platform packages like platform and foundation that are always available.
Characteristics:
- Read-only - cannot be modified.
- Always available (bundled with server).
- No configuration required.
- Provides core C3 Agentic AI Platform Types.
Platform packages are foundational to all C3 applications. You can remix Types from C3 Agentic AI Platform packages to customize them for your application, but you cannot modify the original C3 Agentic AI Platform definitions.
VSCode integration
The VSCode extension relies heavily on Pkg.Store for all IDE features. Every operation goes through the Pkg.Store abstraction to access package files.
Autocomplete: Queries Pkg.Store for package Type names and definitions. If packages aren't in a configured store, autocomplete breaks.
Go-to-definition: Looks up file locations through Pkg.Store. Fails if packages aren't accessible or files are missing.
Type checking: Validates Types using metadata from Pkg.Store. Shows stale information if store isn't synchronized.
Hover documentation: Retrieves Type documentation from Pkg.Store. Shows no information if Type metadata is missing.
See also
- Package Store Overview - How storage fits into the package lifecycle.
- Artifact Hub - Publishing and distributing packages.