openai/codex · error · MemoriesBackendError

ad-hoc note '{filename}' already exists

Error message

ad-hoc note '{filename}' already exists

What it means

MemoriesBackend::add_ad_hoc_note refuses to overwrite: creating a note whose filename already exists in the memory store fails. Ad-hoc notes are create-only at this layer; there is no in-place update path.

Source

Thrown at codex-rs/ext/memories/src/backend.rs:141

}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
pub struct MemorySearchMatch {
    pub path: String,
    pub match_line_number: usize,
    pub content_start_line_number: usize,
    pub content: String,
    pub matched_queries: Vec<String>,
}

#[derive(Debug, thiserror::Error)]
pub enum MemoriesBackendError {
    #[error("filename '{filename}' {reason}")]
    InvalidFilename { filename: String, reason: String },
    #[error("ad-hoc note must not be empty")]
    EmptyAdHocNote,
    #[error("ad-hoc note '{filename}' already exists")]
    AdHocNoteAlreadyExists { filename: String },
    #[error("path '{path}' {reason}")]
    InvalidPath { path: String, reason: String },
    #[error("cursor '{cursor}' {reason}")]
    InvalidCursor { cursor: String, reason: String },
    #[error("path '{path}' was not found")]
    NotFound { path: String },
    #[error("line_offset must be a 1-indexed line number")]
    InvalidLineOffset,
    #[error("max_lines must be a positive integer")]
    InvalidMaxLines,
    #[error("line_offset exceeds file length")]
    LineOffsetExceedsFileLength,
    #[error("path '{path}' is not a file")]
    NotFile { path: String },
    #[error("queries must not be empty or contain empty strings")]
    EmptyQuery,
    #[error("all_within_lines.line_count must be a positive integer")]

View on GitHub (pinned to 339751715c)

Solutions

1. Choose a different (e.g. suffixed) filename for the new note.
2. If updating was intended, read the existing note and store the edited version under a new name.
3. On retries, treat AlreadyExists as success-by-idempotency when appropriate.

match backend.add_ad_hoc_note(request).await {
    Err(MemoriesBackendError::AdHocNoteAlreadyExists { filename }) => {
        tracing::info!(%filename, "note already present; treating replay as idempotent");
        Ok(AddAdHocMemoryNoteResponse {})
    }
    r => r,
}

When it happens

Trigger: add_ad_hoc_note with a filename already present in the store — from a previous call, a synced store, or a replayed request.

Common situations: Retrying a call after a timeout without changing the filename; two writers racing to create the same note; attempting to 'update' by re-adding.

Related errors

• filename '{filename}' {reason}
• ad-hoc note must not be empty
• path '{path}' {reason}
• cursor '{cursor}' {reason}
• path '{path}' was not found

AI-assisted analysis of openai/codex@339751715c (2026-08-25). Data as JSON: /api/errors/1f36eb853d551872. Report an issue: GitHub.