{"record":{"id":"8f39539c73124510","repo":"cilium/cilium","slug":"could-not-determine-clocksource","errorCode":null,"errorMessage":"could not determine clocksource","messagePattern":"could not determine clocksource","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/maps/timestamp/timestamp.go","lineNumber":52,"sourceCode":"}\n\n// Get current clocksource - to be used in the agent context.\nfunc GetClockSourceFromOptions() *models.ClockSource {\n\treturn getClockSourceFromConfig(option.Config)\n}\n\n// Connect to the agent via API and get its current clocksource.\nfunc GetClockSourceFromAgent(svc daemon.ClientService) (*models.ClockSource, error) {\n\tparams := daemon.NewGetHealthzParamsWithTimeout(5 * time.Second)\n\tbrief := false\n\tparams.SetBrief(&brief)\n\tresp, err := svc.GetHealthz(params)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\tif resp.Payload.ClockSource == nil {\n\t\treturn nil, fmt.Errorf(\"could not determine clocksource\")\n\t}\n\n\treturn resp.Payload.ClockSource, nil\n}\n\n// Get the clocksource from the agent config file in case agent is not running.\nfunc GetClockSourceFromRuntimeConfig() (*models.ClockSource, error) {\n\tvar config option.DaemonConfig\n\n\tagentConfigFile := filepath.Join(defaults.RuntimePath, defaults.StateDir,\n\t\t\"agent-runtime-config.json\")\n\n\tif byteValue, err := os.ReadFile(agentConfigFile); err == nil {\n\t\terr = json.Unmarshal(byteValue, &config)\n\t\tif err != nil {\n\t\t\treturn nil, err\n\t\t}\n\t\treturn getClockSourceFromConfig(&config), nil","sourceCodeStart":34,"sourceCodeEnd":70,"githubUrl":"https://github.com/cilium/cilium/blob/ac7b90affa4baf0642e6685319d56907b3a73a6d/pkg/maps/timestamp/timestamp.go#L34-L70","documentation":"GetClockSourceFromAgent queries the cilium agent's Healthz API endpoint and expects a ClockSource object in the response. When the payload's ClockSource field is nil, the library cannot know which clock the BPF timestamps use, so it refuses to guess and returns this error. It is a defensive check against an agent that did not report its clocksource.","triggerScenarios":"Calling GetClockSourceFromAgent against an agent whose /healthz payload has no clock_source field — e.g. an older agent version predating clocksource reporting, a partially initialized agent, or a proxied/mocked health API client returning a stale/empty payload.","commonSituations":"Version skew between client and agent (old agent without clocksource support); agent still starting up before config is populated; health endpoint behind a proxy that drops optional fields.","solutions":["Upgrade or restart the cilium agent so its health payload includes clock_source","Read the clocksource from the agent config file instead (the package provides a config-file path for exactly this case)","Verify the Healthz response payload actually contains clock_source (inspect GET /healthz output)","Ensure the Go client model (models.ClockSource) matches the agent's API version"],"exampleFix":"// before: nil propagates to converter constructors\nclockSource, _ := GetClockSourceFromAgent(svc)\n// after: fall back to config-file clocksource on nil\nresp, err := svc.GetHealthz(params)\nif err != nil {\n    return nil, err\n}\nif resp.Payload.ClockSource == nil {\n    return getClockSourceFromConfig() // fallback path\n}\nreturn resp.Payload.ClockSource, nil","handlingStrategy":"fallback","validationCode":"// Check the payload before trusting it\nresp, _ := svc.GetHealthz(params)\nhasClockSource := resp != nil && resp.Payload != nil && resp.Payload.ClockSource != nil\nif !hasClockSource {\n    // fall back to agent config file clocksource\n}","typeGuard":"func clockSourceKnown(cs *models.ClockSource) bool {\n    return cs != nil && cs.Mode != \"\"\n}","tryCatchPattern":"// Go: fall back to config-file source when API yields none\nclockSource, err := GetClockSourceFromAgent(svc)\nif err != nil {\n    clockSource, err = getClockSourceFromConfig()\n    if err != nil {\n        return fmt.Errorf(\"no clocksource from API or config: %w\", err)\n    }\n}","preventionTips":["Keep agent and client API models version-aligned","Retry health queries briefly on agent startup before giving up","Alert on healthz payloads missing clock_source","Prefer the config-file clocksource path in offline tooling"],"tags":["clocksource","health-api","version-compatibility"],"backgroundTag":"clocksource-undetermined","analyzedSha":"ac7b90affa4baf0642e6685319d56907b3a73a6d","analyzedAt":"2026-08-31T18:27:15.868Z","schemaVersion":2},"datasetVersion":"2026-08-31T19:17:28.585Z"}