{"record":{"id":"3e9aaa99a54474b9","repo":"caddyserver/caddy","slug":"could-not-convert-automation-policy-subject-s-t","errorCode":null,"errorMessage":"could not convert automation policy subject '%s' to punycode: %v","messagePattern":"could not convert automation policy subject '(.+?)' to punycode: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"modules/caddytls/automation.go","lineNumber":190,"sourceCode":"\n\tsubjects []string\n\tmagic    *certmagic.Config\n\tstorage  certmagic.Storage\n\n\t// Whether this policy had explicit managers configured directly on it.\n\thadExplicitManagers bool\n}\n\n// Provision sets up ap and builds its underlying CertMagic config.\nfunc (ap *AutomationPolicy) Provision(tlsApp *TLS) error {\n\t// replace placeholders in subjects to allow environment variables\n\trepl := caddy.NewReplacer()\n\tsubjects := make([]string, len(ap.SubjectsRaw))\n\tfor i, sub := range ap.SubjectsRaw {\n\t\tsub = repl.ReplaceAll(sub, \"\")\n\t\tsubASCII, err := idna.ToASCII(sub)\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"could not convert automation policy subject '%s' to punycode: %v\", sub, err)\n\t\t}\n\t\tsubjects[i] = subASCII\n\t}\n\tap.subjects = subjects\n\n\t// policy-specific storage implementation\n\tif ap.StorageRaw != nil {\n\t\tval, err := tlsApp.ctx.LoadModule(ap, \"StorageRaw\")\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"loading TLS storage module: %v\", err)\n\t\t}\n\t\tcmStorage, err := val.(caddy.StorageConverter).CertMagicStorage()\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"creating TLS storage configuration: %v\", err)\n\t\t}\n\t\tap.storage = cmStorage\n\t}\n","sourceCodeStart":172,"sourceCodeEnd":208,"githubUrl":"https://github.com/caddyserver/caddy/blob/50e54ee279aa1e504fe218ca49ab6ae16c100410/modules/caddytls/automation.go#L172-L208","documentation":"During AutomationPolicy.Provision, each subject (domain name) is passed through the placeholder replacer and then idna.ToASCII to convert it to punycode/ASCII form. If the conversion fails, the subject is not a valid IDNA name. The wrapped error from the idna library explains the exact problem (empty label, disallowed rune, label too long, etc.).","triggerScenarios":"A subject in the automation policy containing characters that cannot be IDNA-encoded: strings longer than 253 bytes, labels over 63 chars, empty labels (double dots), stray underscores placed where IDNA forbids them, or a placeholder that expanded to an empty/invalid name.","commonSituations":"Typos in Caddyfile site addresses (double dots, trailing garbage); environment placeholders like {$DOMAIN} unset so the subject collapses to an empty string; pasting Unicode hostnames with zero-width characters; copy/paste of wildcard names with incorrect syntax.","solutions":["Inspect the subject named in the message and fix or remove the invalid character(s) — the wrapped idna error states the precise cause.","If the subject uses {$ENV_PLACEHOLDER} syntax, confirm the environment variable is set to a valid hostname on the machine running Caddy.","Validate names with a punycode converter (e.g. idn command or an online IDNA tool) before putting them in config.","Remember underscores are not permitted in hostnames per IDNA; remove them or move such names out of the TLS subjects."],"exampleFix":"# before (placeholder unset -> empty/invalid subject)\n{$SITE_DOMAIN}:443 {\n\trespond \"hi\"\n}\n\n# after (valid literal or verified env var)\nexample.com:443 {\n\trespond \"hi\"\n}","handlingStrategy":"validation","validationCode":"// Validate subjects before provisioning.\nfor _, s := range policy.SubjectsRaw {\n    s = repl.ReplaceAll(s, \"\")\n    if _, err := idna.ToASCII(s); err != nil {\n        return fmt.Errorf(\"subject %q fails IDNA: %v\", s, err)\n    }\n}","typeGuard":"func isValidSubjectName(s string) bool {\n    _, err := idna.ToASCII(s)\n    return err == nil\n}","tryCatchPattern":null,"preventionTips":["Lint hostnames in generated configs with idna.ToASCII before deploying.","Fail builds when {$...} site-address placeholders are unset in the target environment.","Avoid underscores and stray dots in site addresses."],"tags":["tls","configuration","dns","idna","validation"],"backgroundTag":null,"analyzedSha":"50e54ee279aa1e504fe218ca49ab6ae16c100410","analyzedAt":"2026-08-15T09:20:21.641Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}