{"record":{"id":"d2e4f59d12a083ac","repo":"flipped-aurora/gin-vue-admin","slug":"panic-err-oracle-database-connection-failed","errorCode":null,"errorMessage":"panic(err) — Oracle database connection failed","messagePattern":"panic\\(err\\) — Oracle database connection failed","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"server/initialize/gorm_oracle.go","lineNumber":32,"sourceCode":"func GormOracle() *gorm.DB {\n\tm := global.GVA_CONFIG.Oracle\n\treturn initOracleDatabase(m)\n}\n\n// GormOracleByConfig 初始化Oracle数据库用过传入配置\nfunc GormOracleByConfig(m config.Oracle) *gorm.DB {\n\treturn initOracleDatabase(m)\n}\n\n// initOracleDatabase 初始化Oracle数据库的辅助函数\nfunc initOracleDatabase(m config.Oracle) *gorm.DB {\n\tif m.Dbname == \"\" {\n\t\treturn nil\n\t}\n\t// 数据库配置\n\tgeneral := m.GeneralDB\n\tif db, err := gorm.Open(oracle.Open(m.Dsn()), internal.Gorm.Config(general)); err != nil {\n\t\tpanic(err)\n\t} else {\n\t\tsqlDB, _ := db.DB()\n\t\tsqlDB.SetMaxIdleConns(m.MaxIdleConns)\n\t\tsqlDB.SetMaxOpenConns(m.MaxOpenConns)\n\t\tsqlDB.SetConnMaxLifetime(time.Duration(m.ConnMaxLifetime) * time.Second)\n\t\treturn db\n\t}\n}\n","sourceCodeStart":14,"sourceCodeEnd":41,"githubUrl":"https://github.com/flipped-aurora/gin-vue-admin/blob/3136500ef380842b0eb6c4daa87c3f8a47fcf9e0/server/initialize/gorm_oracle.go#L14-L41","documentation":"initOracleDatabase opens the Oracle connection via gorm.Open(oracle.Open(m.Dsn())); any driver-level failure (bad DSN, listener unreachable, credentials) returns err which is immediately panicked. Like the MySQL path, this is fail-fast initialization: the server refuses to boot without its Oracle database. Note the guard above it: if Dbname is empty the function returns nil silently, so the panic only fires when an Oracle DB is actually configured.","triggerScenarios":"gorm.Open returns err at startup — malformed Oracle DSN (user/password@host:port/service), Oracle listener down or wrong port, wrong service name/SID, missing oracle driver registration (blank import), or network/firewall blocking the listener; reached via GormOracle/GormOracleByConfig when system.db-type is oracle and dbname is non-empty.","commonSituations":"Switching db-type to oracle without updating DSN fields in config.yaml; typo in service name after an oracle move; ORA-12541 (no listener) because the DB container isn't up; ORA-01017 (invalid username/password); missing Oracle instant client / driver in the build image.","solutions":["Test the DSN with sqlplus <user>/<pass>@//<host>:<port>/<service> from the server host to separate network vs credential issues.","Verify config.yaml oracle block: username, password, path/host, port, dbname — m.Dsn() builds the connect string from these; fix typos.","Confirm the Oracle listener/service is running (lsnrctl status) and the port is reachable (telnet/nc host port).","Ensure the gorm oracle driver blank import exists in gorm_oracle.go and the Oracle client libraries are present in the deployment image.","Read the wrapped ORA-xxxxx code in err — 12541/12170 = network, 01017 = auth, 12514 = wrong service name."],"exampleFix":"// before\nif db, err := gorm.Open(oracle.Open(m.Dsn()), internal.Gorm.Config(general)); err != nil {\n    panic(err)\n}\n// after\nif db, err := gorm.Open(oracle.Open(m.Dsn()), internal.Gorm.Config(general)); err != nil {\n    global.GVA_LOG.Error(\"oracle connect failed\", zap.String(\"dsnHost\", m.Path), zap.Error(err))\n    panic(fmt.Sprintf(\"oracle connect failed: %v\", err))\n}","handlingStrategy":"validation","validationCode":"// preflight DSN reachability before gorm.Open\nconn, err := net.DialTimeout(\"tcp\", fmt.Sprintf(\"%s:%s\", m.Path, m.Port), 3*time.Second)\nif err != nil { return fmt.Errorf(\"oracle unreachable: %w\", err) }","typeGuard":null,"tryCatchPattern":"// log underlying ORA- code before terminating\nif db, err := gorm.Open(oracle.Open(m.Dsn()), internal.Gorm.Config(general)); err != nil {\n    log.Fatalf(\"oracle init failed: %v\", err)\n}","preventionTips":["Validate the Oracle block of config.yaml (path/port/dbname) whenever switching db-type","Test the exact DSN with sqlplus or a small sql.Open+Ping probe during deployment","Ensure Oracle client/driver libs are in the runtime image, not just the build image","Use healthcheck-gated startup order for the Oracle container/service","Triage by ORA- code: 12541/12170 network, 01017 credentials, 12514 service name"],"tags":["oracle","gorm","startup","panic","database"],"backgroundTag":"database-connection-failed","analyzedSha":"3136500ef380842b0eb6c4daa87c3f8a47fcf9e0","analyzedAt":"2026-08-31T13:50:02.721Z","schemaVersion":2},"datasetVersion":"2026-08-31T19:17:28.585Z"}