What causes "parent page ID is required" in gastownhall/beads?

Set the parent page ID in configuration (or pass it explicitly) before calling CreateDatabase.

parent page ID is required

Error message

parent page ID is required

What it means

CreateDatabase requires a parent page ID; an empty/whitespace-only value is rejected before any request is made. Notion databases must be created under a parent page.

Source

Thrown at internal/notion/client.go:91

	return &ds, nil
}

func (c *Client) RetrieveDatabase(ctx context.Context, databaseID string) (*Database, error) {
	body, err := c.doRequest(ctx, http.MethodGet, "/databases/"+url.PathEscape(databaseID), nil)
	if err != nil {
		return nil, err
	}
	var db Database
	if err := json.Unmarshal(body, &db); err != nil {
		return nil, fmt.Errorf("parse database response: %w", err)
	}
	return &db, nil
}

func (c *Client) CreateDatabase(ctx context.Context, parentPageID, title string) (*Database, error) {
	parentPageID = strings.TrimSpace(parentPageID)
	if parentPageID == "" {
		return nil, fmt.Errorf("parent page ID is required")
	}
	title = strings.TrimSpace(title)
	if title == "" {
		title = DefaultDatabaseTitle
	}
	request := map[string]interface{}{
		"parent": map[string]interface{}{
			"type":    "page_id",
			"page_id": parentPageID,
		},
		"title":     richTextRequest(title),
		"is_inline": false,
		"initial_data_source": map[string]interface{}{
			"title":      richTextRequest(title),
			"properties": BuildInitialDataSourceProperties(),
		},
	}
	body, err := c.doRequest(ctx, http.MethodPost, "/databases", request)

View on GitHub (pinned to 71377f2769)

Solutions

Set the parent page ID in configuration (or pass it explicitly) before calling CreateDatabase.
Run the Notion init/validation flow to capture the parent page ID from the user.
Verify with a validation step (strings.TrimSpace check) before invoking.

Example fix

// before
client.CreateDatabase(ctx, cfg.NotionParentPage, "Beads")
// after
if strings.TrimSpace(cfg.NotionParentPage) == "" {
    return fmt.Errorf("configure notion parent page ID first")
}
client.CreateDatabase(ctx, cfg.NotionParentPage, "Beads")

Defensive patterns

Strategy: validation

Validate before calling

if strings.TrimSpace(parentPageID) == "" {
    return errors.New("parent page ID must be configured before creating a database")
}

Try / catch

db, err := client.CreateDatabase(ctx, parentPageID, title)
if err != nil {
    if err.Error() == "parent page ID is required" {
        return fmt.Errorf("run notion init to set the parent page")
    }
    return err
}

Prevention

Validate Notion config (token + parent page) during init
Fail fast on empty required config fields
Document required env/config keys

When it happens

Trigger: Calling CreateDatabase(ctx, "", title) — e.g. from runNotionInitAfterValidation when the Notion parent page ID was never configured or was blank.

Common situations: Missing NOTION_PARENT_PAGE_ID-style config value; config file with empty field; user skipped the init wizard step that collects the parent page.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

AI-assisted analysis of gastownhall/beads@71377f2769 (2026-08-30). Data as JSON: /api/errors/ac3ac114026e1a4e. Report an issue: GitHub.