{"record":{"id":"9331a24c2b38e7a4","repo":"goharbor/harbor","slug":"invalid-filter-syntax","errorCode":null,"errorMessage":"invalid filter syntax","messagePattern":"invalid filter syntax","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/pkg/ldap/ldap.go","lineNumber":54,"sourceCode":"var ErrNotFound = errors.New(\"entity not found\")\n\n// ErrEmptyPassword ...\nvar ErrEmptyPassword = errors.New(\"empty password\")\n\n// ErrInvalidCredential ...\nvar ErrInvalidCredential = errors.New(\"invalid credential\")\n\n// ErrLDAPServerTimeout ...\nvar ErrLDAPServerTimeout = errors.New(\"ldap server network timeout\")\n\n// ErrLDAPPingFail ...\nvar ErrLDAPPingFail = errors.New(\"fail to ping LDAP server\")\n\n// ErrDNSyntax ...\nvar ErrDNSyntax = errors.New(\"invalid DN syntax\")\n\n// ErrInvalidFilter ...\nvar ErrInvalidFilter = errors.New(\"invalid filter syntax\")\n\n// ErrEmptyBaseDN ...\nvar ErrEmptyBaseDN = errors.New(\"empty base dn\")\n\n// ErrEmptySearchDN ...\nvar ErrEmptySearchDN = errors.New(\"empty search dn\")\n\n// Session - define a LDAP session\ntype Session struct {\n\tbasicCfg models.LdapConf\n\tgroupCfg models.GroupConf\n\tldapConn *goldap.Conn\n}\n\n// NewSession create session with configs\nfunc NewSession(basicCfg models.LdapConf, groupCfg models.GroupConf) *Session {\n\treturn &Session{\n\t\tbasicCfg: basicCfg,","sourceCodeStart":36,"sourceCodeEnd":72,"githubUrl":"https://github.com/goharbor/harbor/blob/7b2fd08cc568955cca339afeefab27372840d936/src/pkg/ldap/ldap.go#L36-L72","documentation":"Sentinel error returned by Session.SearchLdapAttribute when the LDAP filter is empty after normalization or fails goldap.CompileFilter — i.e. ldap_search_filter (or a group filter) is blank or syntactically invalid per RFC 2254. It aborts user search (POST /api/v2.0/ldap/users/search), user import, and group search.","triggerScenarios":"ldap_search_filter left empty and the built filter still normalizes to \"\"; a filter with unbalanced parentheses such as \"(objectclass=person\" ; a bare assertion \"objectclass=person\" that the normalizer/compiler rejects; stray quotes or LDAP-special characters ( ) * \\ unescaped in the config value.","commonSituations":"Copying filters from AD documentation that use a different dialect; env-var quoting that strips parens in docker-compose/Kubernetes; leaving the filter empty assuming a default (some directories need at least (objectClass=*)) — note Harbor's normalizeFilter wraps bare assertions but empty-after-normalize is still fatal.","solutions":["Test the exact filter string against your directory first: ldapsearch -H <url> -D <dn> -W -b <base> '(objectclass=person)'.","Use a syntactically complete filter with balanced parentheses, e.g. \"(objectClass=person)\" or \"(&(objectClass=user)(memberOf=CN=dev,OU=groups,DC=example,DC=com))\".","Save via PUT /api/v2.0/configurations (ldap_search_filter) and re-run POST /api/v2.0/ldap/users/search to confirm."],"exampleFix":"# before (unbalanced parens)\ncurl -X PUT https://harbor/api/v2.0/configurations -d '{\"ldap_search_filter\": \"(objectclass=person\"}'\n# after\ncurl -X PUT https://harbor/api/v2.0/configurations -d '{\"ldap_search_filter\": \"(objectclass=person)\"}'","handlingStrategy":"validation","validationCode":"// Go: apply Harbor's own checks to a filter before configuring/using it\nfilter = strings.TrimSpace(filter)\nif filter == \"\" { fail(\"empty ldap_search_filter\") }\nif _, err := goldap.CompileFilter(filter); err != nil {\n    fail(\"filter does not compile: \" + err.Error())\n}","typeGuard":"func isLdapInvalidFilter(err error) bool { return errors.Is(err, ldap.ErrInvalidFilter) }","tryCatchPattern":"if errors.Is(err, ldap.ErrInvalidFilter) {\n    // re-validate ldap_search_filter / group filter with ldapsearch or CompileFilter,\n    // fix parentheses/escaping, save via PUT configurations, then retry the search\n}","preventionTips":["Every filter change goes through ldapsearch first: ldapsearch -b <base> '<filter>' uid.","Keep filters fully parenthesized per RFC 2254 and escape * ( ) \\ NUL.","Beware YAML/env quoting that can mangle parentheses in config pipelines."],"tags":["ldap","filter","config","query-syntax"],"backgroundTag":null,"analyzedSha":"7b2fd08cc568955cca339afeefab27372840d936","analyzedAt":"2026-08-16T00:00:10.961Z","schemaVersion":2},"datasetVersion":"2026-08-16T03:17:38.424Z"}