Initialize an Automerge document

Oct 13, 2025 by wbrum.org 90 views

Introduction

When attempting to generate a sync message using the Automerge.generateSyncMessage function, an error is thrown: "Uncaught bad sharedHeads: the change hashes were not an array of strings". This occurs even though Automerge.getHeads(meta) returns a valid array of strings. In this article, we will delve into the steps to reproduce this error, the expected and observed behavior, and the troubleshooting steps taken to resolve the issue.

Steps to Reproduce

To reproduce this error, follow these steps:

Initialize an Automerge document: Create a new Automerge document using the Automerge.init() function.

let meta = Automerge.init();

2. **Apply one or more changes**: Optionally, apply one or more changes to the document using the `Automerge.change()` function.
3. **Initialize the sync state**: Initialize the sync state using the `Automerge.initSyncState()` function.
   ```javascript
let syncState = Automerge.initSyncState();

Attempt to generate a sync message: Attempt to generate a sync message using the Automerge.generateSyncMessage function.

const [syncMsg, newSyncState] = Automerge.generateSyncMessage(meta, syncState); syncState = newSyncState;

5. **The error is thrown**: The above call throws the error: "Uncaught bad sharedHeads: the change hashes were not an array of strings".

## Expected Behavior

The expected behavior is that a valid sync message (a `Uint8Array`) is generated without error. The document's heads (as returned by `Automerge.getHeads(meta)`) should be an array of strings (e.g., `['04a722cf59207f55df3a99b9657e8ec99c8adf16bf0d9789e34f1be3473d6a60']`).

## Observed Behavior

Despite valid heads being logged, the call to `Automerge.generateSyncMessage(meta, syncState)` fails with the error about the change hashes not being an array of strings.

## Environment

The error occurs in the following environment:

* Automerge version: `@automerge/automerge`: `^2.2.8`
* Node.js version: `20.17.0`
* Browser: Chrome
* Operating System: Mac OSX

## Additional Context

* The document (`meta`) is updated solely using `Automerge.change()` and has not been manually mutated.
* The sync state is initialized with `Automerge.initSyncState()` and isn’t modified elsewhere.
* Logging `Automerge.getHeads(meta)` right before generating the sync message shows a correct array of strings.
* Re-initializing the sync state immediately before calling `generateSyncMessage` did not resolve the error.

## Troubleshooting Steps Taken

* Verified that `meta` is a valid Automerge document by checking its heads.
* Confirmed that `syncState` is properly initialized.
* Ensured that no manual mutations occur on the internal properties of `meta` or `syncState`.

## Conclusion

The error "Uncaught bad sharedHeads: the change hashes were not an array of strings" when generating a sync message using `Automerge.generateSyncMessage` is a complex issue that requires a thorough investigation. The steps to reproduce the error, the expected and observed behavior, and the troubleshooting steps taken have been outlined in this article. If you are experiencing this issue, please provide additional details or further questions, and we will do our best to assist you in resolving the problem.

### Possible Causes

Based on the information provided, there are several possible causes for this error:

* **Invalid sync state**: The sync state may be invalid or corrupted, causing the error when generating the sync message.
* **Manual mutations**: Manual mutations on the internal properties of `meta` or `syncState` may be causing the error.
* **Automerge version**: The version of Automerge being used may be causing the error.

### Solutions

To resolve this issue, the following solutions can be tried:

* **Re-initialize the sync state**: Re-initialize the sync state before calling `generateSyncMessage`.
* **Verify the sync state**: Verify that the sync state is properly initialized and not corrupted.
* **Check for manual mutations**: Check for manual mutations on the internal properties of `meta` or `syncState`.
* **Update Automerge version**: Update the version of Automerge being used to the latest version.

### Further Investigation

If the above solutions do not resolve the issue, further investigation is required to identify the root cause of the error. This may involve:

* **Logging and debugging**: Logging and debugging the code to identify the exact point where the error occurs.
* **Automerge documentation**: Reviewing the Automerge documentation to ensure that the code is being used correctly.
* **Community support**: Seeking support from the Automerge community or the developers of Automerge.<br/>
# Sync Protocol Error: Uncaught "bad sharedHeads: the change hashes were not an array of strings" when generating sync message - Q&A

## Introduction

In our previous article, we explored the issue of the "Uncaught bad sharedHeads: the change hashes were not an array of strings" error when generating a sync message using `Automerge.generateSyncMessage`. In this article, we will provide a Q&A section to address some of the common questions and concerns related to this issue.

## Q: What is the cause of the "Uncaught bad sharedHeads: the change hashes were not an array of strings" error?

A: The cause of this error is not explicitly stated in the Automerge documentation. However, based on the information provided, it is likely that the error is caused by an invalid or corrupted sync state.

## Q: How can I troubleshoot this issue?

A: To troubleshoot this issue, you can try the following steps:

* Verify that the sync state is properly initialized and not corrupted.
* Check for manual mutations on the internal properties of `meta` or `syncState`.
* Re-initialize the sync state before calling `generateSyncMessage`.
* Update the version of Automerge being used to the latest version.

## Q: What are the possible causes of this error?

A: Based on the information provided, the possible causes of this error are:

* Invalid sync state
* Manual mutations on the internal properties of `meta` or `syncState`
* Automerge version

## Q: How can I prevent this error from occurring?

A: To prevent this error from occurring, you can try the following:

* Verify that the sync state is properly initialized and not corrupted.
* Check for manual mutations on the internal properties of `meta` or `syncState`.
* Use the latest version of Automerge.
* Avoid manual mutations on the internal properties of `meta` or `syncState`.

## Q: What are the consequences of this error?

A: The consequences of this error are:

* The sync message generation process fails.
* The error is thrown, and the program crashes.
* The sync state is corrupted, and the program may not function correctly.

## Q: How can I recover from this error?

A: To recover from this error, you can try the following:

* Re-initialize the sync state.
* Update the version of Automerge being used to the latest version.
* Check for manual mutations on the internal properties of `meta` or `syncState`.
* Verify that the sync state is properly initialized and not corrupted.

## Q: Is this error specific to the Am sync protocol?

A: No, this error is not specific to the Am sync protocol. It can occur in any scenario where the `Automerge.generateSyncMessage` function is used.

## Q: Can I use a different version of Automerge to resolve this issue?

A: Yes, you can try using a different version of Automerge to resolve this issue. However, be aware that using an older version of Automerge may introduce other issues or bugs.

## Q: How can I get help with this issue?

A: If you are experiencing this issue, you can try the following:

* Check the Automerge documentation for more information.
* Seek support from the Automerge community or the developers of Automerge.
* Post a question on the Automerge forum or GitHub issues page.
* Contact a professional developer or consultant for assistance.

## Conclusion

The "Uncaught bad sharedHeads: the change hashes were not an array of strings" error when generating a sync message using `Automerge.generateSyncMessage` is a complex issue that requires a thorough investigation. By following the troubleshooting steps and possible causes outlined in this article, you can identify and resolve the issue. If you have any further questions or concerns, please don't hesitate to ask.