FAQ for common errors in ComposeDB + DIDs (Jan 23)

Since the introduction of 0.3.x documentation I’ve had more chances to work with ComposeDB, so I thought to put together a list of some of the errors I’ve seen both myself, within the Discord and in the forums. This way, we can help future developers identify common pitfalls when working with ComposeDB and around some of the concepts I found particularly challenging when working with Ceramic Network.

First of all, please be aware that the following notes take into consideration documentation up to 0.3.x and have been created with the following packages in mind:

    "@ceramicnetwork/blockchain-utils-linking": "^2.0.8",
    "@ceramicnetwork/common": "^2.4.0",
    "@ceramicnetwork/http-client": "^2.3.1",
    "@composedb/client": "^0.3.0",
    "@composedb/devtools": "^0.3.0",
    "@composedb/devtools-node": "^0.3.0",
    "@didtools/cacao": "^1.0.0",
    "@didtools/pkh-ethereum": "^0.0.2",

It’s very likely these comments will be outdated in the incoming months.


  • What node.js version should be used when running Ceramic packages? - I’ve run most packages successfully using v16 and v18, but anything below that will likely throw some errors. Make sure you are using any of the stable releases (i.e., lts/gallium -> v16.19.0, lts/hydrogen -> v18.13.0) to avoid having silly errors that are hard to debug.
  • Which package manager should I use when running Ceramic projects? - The recommended package is pnpm since most libraries are currently being developed with pnpm. Still, I struggled a bit when installing a few packages and ended up defaulting to npm. Since a few Ceramic projects already have a package-lock.json I avoided yarn in most cases.
  • Which packages should I still globally? - In general you will skip a few headaches if you at least install the cli globally (i.e., pnpm add -g @composedb/cli@^0.3.0, funny enough for global packages pnpm seems to be “better”). Remember that some commands that use npx need to have a reference to the package (e.g., npx -p @ceramicnetwork/cli ceramic daemon).
  • What’s the easiest way to get started developing a Ceramic application? - The Ceramic team recently launched a Create Ceramic App template, which does an amazing job setting everything together for a Ceramic app using ComposeDB. To understand Ceramic DIDs, I recommend this video and for ComposeDB this video.


  • How to start the daemon? - The recommended way is via the command CERAMIC_ENABLE_EXPERIMENTAL_COMPOSE_DB='true' pnpm dlx @ceramicnetwork/cli daemon. Documentation for production deployments is still in progress.
  • What’s this DID_PRIVATE_KEY I need to setup? - It’s nothing more than a private key, but it’s used to generate an identity, particularly as an “Admin” for ComposeDB. You can use composedb did:generate-private-key, and remember that most references for this key are for the 32 bytes hexadecimal value and not its did representation. Most setup errors come from missing this key.
  • What’s the Admin DID for? - It’s the identity required on the “server” side of the composeDB to setup a Composite for your node. You can write data into your Ceramic node with any DID, but the Admin DID is the only one able to modify schemas, composites et. al.
  • What services and ports are important for ComposeDB? - A “successful” Ceramic daemon will kickstart the following process in the respective ports: Ceramic API in 7007, GraphQLi instance in 5001, IPFS lib-p2p swarm port in 4001. Other services might appear, and whenever these ports are busy they will iterate to the next second digit (e.g. 5001 to 5011).
  • Why would I use ComposeDB? - Within the Ceramic Network, you can have DIDs write against streams, which are browsable by Id. You can’t easily fetch this information if you don’t know these Ids. ComposeDB allows you to compose and query data from various streams to easily showcase in your application without having to keep track of these yourself.
  • I got some weird anchor commit error, what is that about? - Bear in mind right now, the Ceramic nodes use particular CAS nodes by the Ceramic team, which as with any infrastructure, if it is down or attacked, it might affect your developer experience.


  • What is the most up-to-date way to write against a stream in Ceramic? - If you are new to Ceramic, I recommend straight away using only did-session, as moving forward that seems to be the way to go. In the past, there have been other SDKs like Self.ID, Glaze and 3Box-DID, so you might see these terms across the documentation.
  • What’s did-session good for? - Unlike other DID providers previously mentioned, did-session provides you with a text representation of your DID which you can use to create semi-permanent sessions for your users, as long as they are able to retrieve these from a localStorage or similar. Be aware sessions do expire, throwing a few odd errors when they do.
  • I want to control a DID with my Ethereum account, how can I do that? - The best place to start is here, and the package in question you’ll need is @didtools/pkh-ethereum which is able to take an Ethereum provider. There are other providers, of course.
  • Can I create and control a DID w/o an Ethereum account and write against a Ceramic node? - Yes. Not all use cases of the Ceramic network rely on an blockchain account. For example, you could manage a DID from a server using a key provider.
  • What are great examples of usage of the Ceramic network that isn’t the Create Ceramic App? - My favorite is Sigle, which showcases the usage of did-session with Ethereum accounts quite well with React and useContext.


  • Wen token? - There’s no communication about any token or any incentives from the Ceramic team. Right now most testnets are handled by the Ceramic network team, although there had been multiple exercises in the past to increase the number of Ceramic nodes by other parties.
  • What’s the history behind Ceramic - This doesn’t fit in a post, but you can google uPort and 3Box to get an idea of some of the first projects around decentralized identifiers.
  • Does the Ceramic Network has anything to do with Ceramic tiles? - No.

Just rediscovering this thread and want to give you a big shout-out @jjperezaguinaga for putting this FAQ list together!

Tagging in @Justina from DevRel for vis

1 Like