Libraries Getting Unlinked After Course Import – Expected Behavior or Bug?

Educators Authoring
, ,
1

Hello Community,

I would like to seek clarification regarding the behavior of library linking during course import in Open edX.

Background / Context

We are working with library-based courses. As part of our deployment process:

  1. Libraries are released first from the development environment.

  2. The course is then exported and imported into another environment (e.g., staging or production).

However, after importing the course, we are observing that the linked content libraries are getting unlinked. As a result, we must manually relink the libraries for each module, which significantly increases manual effort and delays the release process.

User Story

  • As a course creator, I want the process of releasing library-based courses to be streamlined so that manual effort during course imports is minimized.

  • When releasing an updated version of a course, I expect linked libraries to remain intact after import, so the release process is not delayed by manual relinking.

Expected Behavior

Based on prior understanding and internal discussions, linked libraries should:

  • Remain linked after course import.

  • Automatically update to the appropriate released version without requiring manual intervention.

I have observed that this functionality was previously working as intended, where library links were preserved and automatically updated during course import.

Current Issue

Currently, linked libraries are being unlinked after course import, requiring manual relinking. This appears to deviate from the expected automatic linking behavior.

Questions

  1. Is this the expected behavior in the current Open edX version?

  2. If not, should this be considered a bug?

  3. Are there any configuration settings or best practices we should verify to ensure libraries remain linked during course import?

  4. Has anyone else experienced similar behavior in recent releases?

Any guidance, documentation references, or insights would be greatly appreciated.

Thank you in advance for your support.

1 Like
2

Thanks for posting this. I am also facing same issue. does any one has any idea about this? is it a bug or an expected behaviour?

3

We ran into something very similar in one of our Open edX setups, so I can share what we observed.

In newer Open edX releases, library references in exported/imported courses don’t always behave as “hard links” anymore. Instead, during import, they can get converted into detached references depending on how the export was generated and the library versioning state in the target environment. That’s why you may see them appearing “unlinked” and needing manual reattachment.

From what we found:

  • If the libraries weren’t explicitly published/released in the target environment before import, links often break.

  • Some import pipelines treat library blocks as snapshots rather than live references.

  • Version mismatches between environments can also cause the system to drop the association even if IDs look correct.

So in many cases, this does seem like expected behavior in more recent releases rather than a pure bug—though it definitely feels like a regression compared to older workflows.

Workarounds that helped us:

  • Ensure libraries are fully published in the destination environment before course import.

  • Keep library + course exports aligned from the same release point.

  • Avoid mixing draft library states with released course exports.

If you’re trying to streamline course tooling or even just organizing resources, we also found some helpful utility tools around content structuring like this one name generator free (we used it internally for quick naming consistency when dealing with multiple libraries/modules).

That said, if you’re on a newer release (Nutmeg/Oxygen or later), I’d still flag this as worth checking in Open edX’s tracker, because the UX regression around relinking is painful for large course sets.

Would be interested to know what version you’re on and whether your libraries are XBlocks-based or the newer Library V2 format—that usually changes the behavior a lot.