OpenKatana · Save composition:
OpenKatana_save_composition saves an OpenKatana composition document as a JSON file inside your project, helping you preserve an editable design rather than just a rendered image or video. Before saving, it checks that the document meets the composition requirements and that the destination is suitable for a composition file. It also protects your work against accidental overwrites by checking whether the saved composition has changed since you last loaded it. When replacing an existing composition, it stores the previous document in the project’s composition history. A temporary lock prevents overlapping saves to the same file. This node is for saving composition data; it does not render frames, generate a preview, or export a video.
OpenKatana · Save composition Input Parameters:
project_id
A required STRING identifying the OpenKatana project in which you want to save the composition. The node passes this identifier through its tool-argument preparation process so the save operation can work with the appropriate project context. Choose the project that contains the composition’s referenced assets and intended destination, because validation and file handling use the resolved project root. The supplied interface does not show a default value, a list of available project identifiers, or minimum and maximum string lengths.
arguments
A required STRING containing the save tool’s arguments as JSON text. The underlying save operation needs a destination path, a composition document, and a revision; these belong inside this JSON string and are not separate node inputs. The destination must resolve to an allowed location within the project, must have the exact extension .json, and cannot be the project-root project.json or timeline.json. The document must satisfy OpenKatana’s composition validation rules. The revision is an overwrite-safety check: use JSON null when creating a file that does not exist, or supply the current revision of an existing document when updating it. If the revision does not match the file currently on disk, the save is rejected. A conceptual argument structure is {"path":"compositions/title.json","document":...,"revision":null}; replace the ellipsis with a complete valid composition object before using it. No default string, length limits, or complete document-schema options are shown in the supplied interface.
after
An optional STRING with a default of None in the execution method. The supplied implementation accepts this value but does not read it, include it in the tool arguments, or use it to change the save operation. A connection to this input can provide a graph dependency when you need another node to execute first, but its string contents are not a composition revision, destination, or save setting. No minimum or maximum length, selectable options, or additional behavior is defined in the supplied source.
OpenKatana · Save composition Output Parameters:
result_json
A STRING containing the tool response serialized by the node’s response helper. The underlying successful save returns a path and a revision: path is the saved file’s location relative to the project root, using forward slashes, and revision is a fingerprint calculated from the saved composition document. Keep that revision so you can safely update the same composition later; it lets OpenKatana verify that you are not overwriting changes made after your last save or load. The supplied code does not show the response helper’s implementation, so the exact outer JSON structure cannot be confirmed here. This output is a save response, not an image, rendered clip, or copy of the complete composition.
OpenKatana · Save composition Usage Tips:
- Use a dedicated composition location such as
compositions/title.json. Keep composition documents separate from the project-rootproject.jsonandtimeline.jsonfiles. - For a new destination, include
"revision":nullinarguments. For an existing destination, use its current revision instead; passingnulldoes not mean “overwrite regardless.” - Preserve the revision returned after each successful save. Use that updated value for the next save, because a changed document normally has a different fingerprint.
- Build
argumentsas valid JSON: use double quotes for property names and strings, and usenullrather than Python’sNone. Supply the actual composition object underdocument, not a filename pointing to it. - If you receive a revision-conflict error, reload the current composition and review its changes before saving again. Simply replacing the revision without checking the document can overwrite work you intended to keep.
- Avoid running multiple save branches against the same destination at the same time. Sequence them when necessary, and make sure each subsequent update has the correct current revision.
- Existing versions are saved under
.openkatana/composition-historyusing their fingerprints as filenames. This provides previous document data, but the shown implementation does not provide a restore control or a history-management interface. - Use a separate inspection or rendering operation when you need visual confirmation. Saving validates the composition document, but it does not run the browser-based rendering and layout checks shown elsewhere in the supplied context.
OpenKatana · Save composition Common Errors and Solutions:
Use a composition .json path distinct from project/timeline
- Explanation: The destination does not have the exact
.jsonextension, or it points to the project-rootproject.jsonortimeline.json. These root files are reserved for other project data. - Solution: Choose a separate destination such as
compositions/title.json. Use the lowercase.jsonextension.
Composition changed; reload before saving
- Explanation: The supplied revision does not match the existing document’s fingerprint. This can happen if another operation changed the file, if you reused an older revision, or if you passed
nullfor a file that already exists. It can also occur when you supply an existing-file revision for a destination that no longer exists. - Solution: Reload the current destination and obtain its revision, review any differences, then retry with the document you intend to save and the correct revision. Use
nullonly when the destination does not exist.
Composition save is already in progress; inspect a stale lock before retrying
- Explanation: The save encountered an existing-file condition while attempting its protected save sequence, normally because the destination’s temporary lock file already exists. For
title.json, that lock istitle.json.lock. Another save may still be running, or an interrupted operation may have left the lock behind. - Solution: Wait for any active save to finish and retry. If no save is running, inspect the lock and remove it only after confirming that it is stale. Do not delete a lock belonging to an active save.
Invalid JSON in arguments
- Explanation: The argument text cannot be interpreted as JSON, for example because it contains single-quoted strings, a trailing comma, Python’s
None, or an unreplaced ellipsis from an example. The exact parser error text is not shown in the supplied source. - Solution: Check the argument text with a JSON validator. Use double quotes, replace placeholders with actual document content, and write an empty revision as
null.
Composition document validation failure
- Explanation: The save operation validates the composition before writing it. A document that does not meet OpenKatana’s requirements is rejected; the supplied excerpt does not include the complete validation rules or their exact error messages.
- Solution: Follow the specific validation message returned by OpenKatana. Start from a known-valid composition and check the fields or referenced resources identified by the error. Do not use a timeline document as a substitute for a composition document.
Destination path rejected
- Explanation: The destination is resolved through OpenKatana’s project-local path handling before saving. A path that fails those rules cannot be used. The exact path-validation messages are not included in the supplied context.
- Solution: Use a simple project-relative location such as
compositions/title.jsonand avoid paths intended to escape the project directory.
Permission denied or other file-system write error
- Explanation: Saving requires access to create the destination’s parent folders, create a lock file, write the composition, and, when replacing a file, write its previous version to the history folder. File-system restrictions can interrupt any of these steps; exact wording depends on the operating system.
- Solution: Check that the account running ComfyUI can write to the destination and
.openkatana/composition-history. Also check available disk space. After an interrupted operation, confirm whether the destination changed before retrying with the same revision.
Existing composition contains invalid JSON
- Explanation: When the destination already exists, the save operation reads it as JSON before checking its revision and preserving its history. A damaged or manually edited file that is no longer valid JSON can cause parsing to fail.
- Solution: Back up the affected file before making changes, then repair its JSON or restore a valid copy. Alternatively, save your valid composition to a new destination with
"revision":nullwhile you investigate the original file.
