openai/codex · error · MemoriesBackendError

filename '{filename}' {reason}

Error message

filename '{filename}' {reason}

What it means

MemoriesBackend::add_ad_hoc_note validates the requested filename before storing; the reason string completes the sentence ('filename X <reason>') and names the exact violation. Backends keep paths relative to the memory store, so filenames must be plain single-component names.

Source

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

#[serde(rename_all = "snake_case")]
pub enum MemoryEntryType {
    File,
    Directory,
}

#[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")]

View on GitHub (pinned to 339751715c)

Solutions

1. Read the reason field — it states the precise rule broken.
2. Use a plain single-component filename (letters, digits, dash, underscore, extension).
3. Sanitize or normalize filenames before calling add_ad_hoc_note.
4. Generate slug names from titles instead of accepting raw input.

Example fix

// before
backend.add_ad_hoc_note(AddAdHocMemoryNoteRequest {
    filename: "../notes/My Note.md".into(),
    note,
}).await?;

// after
backend.add_ad_hoc_note(AddAdHocMemoryNoteRequest {
    filename: "my-note.md".into(),
    note,
}).await?;

let filename = sanitize(&raw_title); // slug: lowercase, [-a-z0-9_.]
if !is_valid_memory_filename(&filename) {
    return Err(MemoriesBackendError::invalid_filename(filename, "contains path separators"));
}

fn is_valid_memory_filename(name: &str) -> bool {
    !name.is_empty()
        && !name.starts_with('.')
        && !name.contains(['/', '\\', ':'])
        && !name.contains("..")
        && name == name.trim()
}

When it happens

Trigger: add_ad_hoc_note with a filename containing path separators, '..' traversal, invalid characters, or otherwise violating the backend's storage rules (the reason says which).

Common situations: Letting model or user input become the filename verbatim; porting note names from another OS (backslashes, colons); hidden or relative names.

Related errors

• ad-hoc note must not be empty
• path '{path}' {reason}
• line_offset must be a 1-indexed line number
• max_lines must be a positive integer
• path '{path}' is not a file

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