ory/hydra · error

plan must define at least one PageTokenColumn

Error message

plan must define at least one PageTokenColumn

What it means

Returned by NewPaginationPlanner when the fallback plan's default page token defines no columns. A keyset pagination plan is meaningless without at least one PageTokenColumn to order by, so the planner cannot be constructed. This is a setup/configuration bug in the caller, not a runtime data problem.

Source

Thrown at oryx/pagination/paginationplanner/planner.go:22

package paginationplanner

import (
	"github.com/pkg/errors"

	keysetpagination "github.com/ory/x/pagination/keysetpagination_v2"
)

// PaginationPlanner chooses the best [PaginationPlan] for a queriedColumns.
// Plan is eligible when its required constraint set is satisfied (and an optional Condition matches).
// If no plan matches, the FallbackPlan is used.
type PaginationPlanner struct {
	Plans        []PaginationPlan
	FallbackPlan PaginationPlan
}

func NewPaginationPlanner(fallbackPlan PaginationPlan, plans []PaginationPlan) (*PaginationPlanner, error) {
	if len(fallbackPlan.DefaultPageToken.Columns()) == 0 {
		return nil, errors.New("plan must define at least one PageTokenColumn")
	}

	for i := range plans {
		plan := &plans[i]
		if len(plan.ApplicableQueries) == 0 {
			return nil, errors.New("plan must define at least one ApplicableQueries")
		}
		if len(plan.DefaultPageToken.Columns()) == 0 {
			return nil, errors.New("plan must define a DefaultPageToken")
		}
		plan.populateInternals()
	}

	return &PaginationPlanner{
		Plans:        plans,
		FallbackPlan: fallbackPlan,
	}, nil
}

View on GitHub (pinned to 4174065ffb)

Solutions

1. Give the fallback plan's DefaultPageToken at least one keysetpagination.PageTokenColumn
2. Verify the plan builder actually appends columns instead of returning an empty slice
3. Add a startup test that constructs the planner so misconfiguration fails fast in CI

When it happens

Trigger: Thrown at oryx/pagination/paginationplanner/planner.go:22 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of ory/hydra@4174065ffb (2026-09-03). Data as JSON: /api/errors/db6ed863c1b22052. Report an issue: GitHub.