[{"data":1,"prerenderedAt":1644},["ShallowReactive",2],{"\u002Ffix-issues\u002Fflask-gunicorn-service-failed-to-start":3},{"id":4,"title":5,"body":6,"description":1634,"extension":1635,"meta":1636,"navigation":101,"path":1640,"seo":1641,"stem":1642,"__hash__":1643},"content\u002Ffix-issues\u002Fflask-gunicorn-service-failed-to-start.md","Flask Gunicorn Service Failed to Start",{"type":7,"value":8,"toc":1623},"minimark",[9,13,17,22,25,177,184,188,197,200,204,1075,1079,1169,1173,1176,1347,1350,1392,1397,1401,1490,1497,1501,1515,1519,1534,1542,1553,1561,1573,1588,1600,1612,1616,1619],[10,11,5],"h1",{"id":12},"flask-gunicorn-service-failed-to-start",[14,15,16],"p",{},"If your Flask Gunicorn service fails to start in production, this guide shows you how to identify the startup failure, correct the systemd or Gunicorn configuration, and bring the app back online. Use it to fix failed units, bad paths, missing dependencies, environment issues, and socket binding errors step-by-step.",[18,19,21],"h2",{"id":20},"quick-fix-quick-setup","Quick Fix \u002F Quick Setup",[14,23,24],{},"Run these commands first:",[26,27,32],"pre",{"className":28,"code":29,"language":30,"meta":31,"style":31},"language-bash shiki shiki-themes github-light github-dark","sudo systemctl status gunicorn --no-pager -l\nsudo journalctl -u gunicorn -n 100 --no-pager\nsudo systemctl cat gunicorn\n\n# Validate the app manually as the service user\nsudo -u www-data \u002Fpath\u002Fto\u002Fvenv\u002Fbin\u002Fgunicorn --bind 127.0.0.1:8000 wsgi:app\n\n# After fixing paths\u002Fuser\u002Fenv, reload and restart\nsudo systemctl daemon-reload\nsudo systemctl restart gunicorn\nsudo systemctl enable gunicorn\n","bash","",[33,34,35,61,83,96,103,110,132,137,143,153,165],"code",{"__ignoreMap":31},[36,37,40,44,48,51,54,58],"span",{"class":38,"line":39},"line",1,[36,41,43],{"class":42},"sScJk","sudo",[36,45,47],{"class":46},"sZZnC"," systemctl",[36,49,50],{"class":46}," status",[36,52,53],{"class":46}," gunicorn",[36,55,57],{"class":56},"sj4cs"," --no-pager",[36,59,60],{"class":56}," -l\n",[36,62,64,66,69,72,74,77,80],{"class":38,"line":63},2,[36,65,43],{"class":42},[36,67,68],{"class":46}," journalctl",[36,70,71],{"class":56}," -u",[36,73,53],{"class":46},[36,75,76],{"class":56}," -n",[36,78,79],{"class":56}," 100",[36,81,82],{"class":56}," --no-pager\n",[36,84,86,88,90,93],{"class":38,"line":85},3,[36,87,43],{"class":42},[36,89,47],{"class":46},[36,91,92],{"class":46}," cat",[36,94,95],{"class":46}," gunicorn\n",[36,97,99],{"class":38,"line":98},4,[36,100,102],{"emptyLinePlaceholder":101},true,"\n",[36,104,106],{"class":38,"line":105},5,[36,107,109],{"class":108},"sJ8bj","# Validate the app manually as the service user\n",[36,111,113,115,117,120,123,126,129],{"class":38,"line":112},6,[36,114,43],{"class":42},[36,116,71],{"class":56},[36,118,119],{"class":46}," www-data",[36,121,122],{"class":46}," \u002Fpath\u002Fto\u002Fvenv\u002Fbin\u002Fgunicorn",[36,124,125],{"class":56}," --bind",[36,127,128],{"class":46}," 127.0.0.1:8000",[36,130,131],{"class":46}," wsgi:app\n",[36,133,135],{"class":38,"line":134},7,[36,136,102],{"emptyLinePlaceholder":101},[36,138,140],{"class":38,"line":139},8,[36,141,142],{"class":108},"# After fixing paths\u002Fuser\u002Fenv, reload and restart\n",[36,144,146,148,150],{"class":38,"line":145},9,[36,147,43],{"class":42},[36,149,47],{"class":46},[36,151,152],{"class":46}," daemon-reload\n",[36,154,156,158,160,163],{"class":38,"line":155},10,[36,157,43],{"class":42},[36,159,47],{"class":46},[36,161,162],{"class":46}," restart",[36,164,95],{"class":46},[36,166,168,170,172,175],{"class":38,"line":167},11,[36,169,43],{"class":42},[36,171,47],{"class":46},[36,173,174],{"class":46}," enable",[36,176,95],{"class":46},[14,178,179,180,183],{},"Most startup failures come from an incorrect ",[33,181,182],{},"ExecStart"," path, wrong working directory, missing virtualenv package, wrong WSGI module, or a service user that cannot access the app directory or socket.",[18,185,187],{"id":186},"whats-happening","What’s Happening",[14,189,190,193,194,196],{},[33,191,192],{},"systemd"," starts Gunicorn using the unit file, configured user, working directory, environment, and ",[33,195,182],{}," command. If any part of that chain is invalid, systemd marks the service as failed before Nginx can proxy requests to Flask.",[14,198,199],{},"Typical failures include import errors, missing Python packages, permission problems, bad bind targets, and invalid unit configuration.",[18,201,203],{"id":202},"step-by-step-guide","Step-by-Step Guide",[205,206,207,264,307,364,427,471,524,571,669,727,784,886,914,934,980,1037],"ol",{},[208,209,210,214,217,218,237,239,240],"li",{},[211,212,213],"strong",{},"Check the current failure state",[215,216],"br",{},"Run:",[26,219,221],{"className":28,"code":220,"language":30,"meta":31,"style":31},"sudo systemctl status gunicorn --no-pager -l\n",[33,222,223],{"__ignoreMap":31},[36,224,225,227,229,231,233,235],{"class":38,"line":39},[36,226,43],{"class":42},[36,228,47],{"class":46},[36,230,50],{"class":46},[36,232,53],{"class":46},[36,234,57],{"class":56},[36,236,60],{"class":56},[215,238],{},"Look for:",[241,242,243,248,253,258,261],"ul",{},[208,244,245],{},[33,246,247],{},"code=exited",[208,249,250],{},[33,251,252],{},"status=203\u002FEXEC",[208,254,255],{},[33,256,257],{},"Permission denied",[208,259,260],{},"Python traceback",[208,262,263],{},"bind errors",[208,265,266,269,217,271,293,295,296],{},[211,267,268],{},"Read the Gunicorn service logs",[215,270],{},[26,272,274],{"className":28,"code":273,"language":30,"meta":31,"style":31},"sudo journalctl -u gunicorn -n 200 --no-pager\n",[33,275,276],{"__ignoreMap":31},[36,277,278,280,282,284,286,288,291],{"class":38,"line":39},[36,279,43],{"class":42},[36,281,68],{"class":46},[36,283,71],{"class":56},[36,285,53],{"class":46},[36,287,76],{"class":56},[36,289,290],{"class":56}," 200",[36,292,82],{"class":56},[215,294],{},"Identify whether the failure happens:",[241,297,298,301,304],{},[208,299,300],{},"before Gunicorn starts",[208,302,303],{},"during Flask app import",[208,305,306],{},"while binding the socket or port",[208,308,309,312,217,314,329,331,332],{},[211,310,311],{},"Inspect the active systemd unit",[215,313],{},[26,315,317],{"className":28,"code":316,"language":30,"meta":31,"style":31},"sudo systemctl cat gunicorn\n",[33,318,319],{"__ignoreMap":31},[36,320,321,323,325,327],{"class":38,"line":39},[36,322,43],{"class":42},[36,324,47],{"class":46},[36,326,92],{"class":46},[36,328,95],{"class":46},[215,330],{},"Verify these fields:",[241,333,334,339,344,349,354,359],{},[208,335,336],{},[33,337,338],{},"User=",[208,340,341],{},[33,342,343],{},"Group=",[208,345,346],{},[33,347,348],{},"WorkingDirectory=",[208,350,351],{},[33,352,353],{},"Environment=",[208,355,356],{},[33,357,358],{},"EnvironmentFile=",[208,360,361],{},[33,362,363],{},"ExecStart=",[208,365,366,369,217,371,408,410,411],{},[211,367,368],{},"Confirm the Gunicorn binary exists in the expected virtualenv",[215,370],{},[26,372,374],{"className":28,"code":373,"language":30,"meta":31,"style":31},"ls -l \u002Fpath\u002Fto\u002Fvenv\u002Fbin\u002Fgunicorn\nsource \u002Fpath\u002Fto\u002Fvenv\u002Fbin\u002Factivate\npip show gunicorn flask\n",[33,375,376,387,395],{"__ignoreMap":31},[36,377,378,381,384],{"class":38,"line":39},[36,379,380],{"class":42},"ls",[36,382,383],{"class":56}," -l",[36,385,386],{"class":46}," \u002Fpath\u002Fto\u002Fvenv\u002Fbin\u002Fgunicorn\n",[36,388,389,392],{"class":38,"line":63},[36,390,391],{"class":56},"source",[36,393,394],{"class":46}," \u002Fpath\u002Fto\u002Fvenv\u002Fbin\u002Factivate\n",[36,396,397,400,403,405],{"class":38,"line":85},[36,398,399],{"class":42},"pip",[36,401,402],{"class":46}," show",[36,404,53],{"class":46},[36,406,407],{"class":46}," flask\n",[215,409],{},"If packages are missing:",[26,412,414],{"className":28,"code":413,"language":30,"meta":31,"style":31},"pip install gunicorn flask\n",[33,415,416],{"__ignoreMap":31},[36,417,418,420,423,425],{"class":38,"line":39},[36,419,399],{"class":42},[36,421,422],{"class":46}," install",[36,424,53],{"class":46},[36,426,407],{"class":46},[208,428,429,432,217,434,456,458,459],{},[211,430,431],{},"Verify the working directory and project files",[215,433],{},[26,435,437],{"className":28,"code":436,"language":30,"meta":31,"style":31},"cd \u002Fpath\u002Fto\u002Fapp && ls -la\n",[33,438,439],{"__ignoreMap":31},[36,440,441,444,447,451,453],{"class":38,"line":39},[36,442,443],{"class":56},"cd",[36,445,446],{"class":46}," \u002Fpath\u002Fto\u002Fapp",[36,448,450],{"class":449},"sVt8B"," && ",[36,452,380],{"class":42},[36,454,455],{"class":56}," -la\n",[215,457],{},"Confirm the Flask project root contains the expected entrypoint, such as:",[241,460,461,466],{},[208,462,463],{},[33,464,465],{},"wsgi.py",[208,467,468],{},[33,469,470],{},"app.py",[208,472,473,476,217,478,507,509,510],{},[211,474,475],{},"Test the WSGI import manually",[215,477],{},[26,479,481],{"className":28,"code":480,"language":30,"meta":31,"style":31},"cd \u002Fpath\u002Fto\u002Fapp\nsource \u002Fpath\u002Fto\u002Fvenv\u002Fbin\u002Factivate\npython -c \"from wsgi import app; print(app)\"\n",[33,482,483,490,496],{"__ignoreMap":31},[36,484,485,487],{"class":38,"line":39},[36,486,443],{"class":56},[36,488,489],{"class":46}," \u002Fpath\u002Fto\u002Fapp\n",[36,491,492,494],{"class":38,"line":63},[36,493,391],{"class":56},[36,495,394],{"class":46},[36,497,498,501,504],{"class":38,"line":85},[36,499,500],{"class":42},"python",[36,502,503],{"class":56}," -c",[36,505,506],{"class":46}," \"from wsgi import app; print(app)\"\n",[215,508],{},"If this fails, fix:",[241,511,512,515,518,521],{},[208,513,514],{},"module names",[208,516,517],{},"import paths",[208,519,520],{},"app object name",[208,522,523],{},"configuration loading during import",[208,525,526,529,531,532,554,556,557],{},[211,527,528],{},"Run Gunicorn manually as the service user",[215,530],{},"Use the same user configured in the unit file:",[26,533,535],{"className":28,"code":534,"language":30,"meta":31,"style":31},"sudo -u www-data bash -lc 'cd \u002Fpath\u002Fto\u002Fapp && \u002Fpath\u002Fto\u002Fvenv\u002Fbin\u002Fgunicorn --bind 127.0.0.1:8000 wsgi:app'\n",[33,536,537],{"__ignoreMap":31},[36,538,539,541,543,545,548,551],{"class":38,"line":39},[36,540,43],{"class":42},[36,542,71],{"class":56},[36,544,119],{"class":46},[36,546,547],{"class":46}," bash",[36,549,550],{"class":56}," -lc",[36,552,553],{"class":46}," 'cd \u002Fpath\u002Fto\u002Fapp && \u002Fpath\u002Fto\u002Fvenv\u002Fbin\u002Fgunicorn --bind 127.0.0.1:8000 wsgi:app'\n",[215,555],{},"This is one of the fastest ways to expose:",[241,558,559,562,565,568],{},[208,560,561],{},"path problems",[208,563,564],{},"permission failures",[208,566,567],{},"missing environment variables",[208,569,570],{},"import errors",[208,572,573,576,578,579,657,659,660],{},[211,574,575],{},"Validate or replace the systemd service definition",[215,577],{},"Example working unit:",[26,580,584],{"className":581,"code":582,"language":583,"meta":31,"style":31},"language-ini shiki shiki-themes github-light github-dark","[Unit]\nDescription=Gunicorn for Flask app\nAfter=network.target\n\n[Service]\nUser=www-data\nGroup=www-data\nWorkingDirectory=\u002Fvar\u002Fwww\u002Fmyapp\nEnvironment=\"PATH=\u002Fvar\u002Fwww\u002Fmyapp\u002Fvenv\u002Fbin\"\nExecStart=\u002Fvar\u002Fwww\u002Fmyapp\u002Fvenv\u002Fbin\u002Fgunicorn --workers 3 --bind 127.0.0.1:8000 wsgi:app\nRestart=always\n\n[Install]\nWantedBy=multi-user.target\n","ini",[33,585,586,591,596,601,605,610,615,620,625,630,635,640,645,651],{"__ignoreMap":31},[36,587,588],{"class":38,"line":39},[36,589,590],{},"[Unit]\n",[36,592,593],{"class":38,"line":63},[36,594,595],{},"Description=Gunicorn for Flask app\n",[36,597,598],{"class":38,"line":85},[36,599,600],{},"After=network.target\n",[36,602,603],{"class":38,"line":98},[36,604,102],{"emptyLinePlaceholder":101},[36,606,607],{"class":38,"line":105},[36,608,609],{},"[Service]\n",[36,611,612],{"class":38,"line":112},[36,613,614],{},"User=www-data\n",[36,616,617],{"class":38,"line":134},[36,618,619],{},"Group=www-data\n",[36,621,622],{"class":38,"line":139},[36,623,624],{},"WorkingDirectory=\u002Fvar\u002Fwww\u002Fmyapp\n",[36,626,627],{"class":38,"line":145},[36,628,629],{},"Environment=\"PATH=\u002Fvar\u002Fwww\u002Fmyapp\u002Fvenv\u002Fbin\"\n",[36,631,632],{"class":38,"line":155},[36,633,634],{},"ExecStart=\u002Fvar\u002Fwww\u002Fmyapp\u002Fvenv\u002Fbin\u002Fgunicorn --workers 3 --bind 127.0.0.1:8000 wsgi:app\n",[36,636,637],{"class":38,"line":167},[36,638,639],{},"Restart=always\n",[36,641,643],{"class":38,"line":642},12,[36,644,102],{"emptyLinePlaceholder":101},[36,646,648],{"class":38,"line":647},13,[36,649,650],{},"[Install]\n",[36,652,654],{"class":38,"line":653},14,[36,655,656],{},"WantedBy=multi-user.target\n",[215,658],{},"Save it as:",[26,661,663],{"className":28,"code":662,"language":30,"meta":31,"style":31},"\u002Fetc\u002Fsystemd\u002Fsystem\u002Fgunicorn.service\n",[33,664,665],{"__ignoreMap":31},[36,666,667],{"class":38,"line":39},[36,668,662],{"class":42},[208,670,671,674,676,677,679,680,682,683,685,686,710,712,713],{},[211,672,673],{},"Validate environment variables",[215,675],{},"If your app depends on secret keys, database URLs, or Flask settings, load them with ",[33,678,353],{}," or ",[33,681,358],{},".",[215,684],{},"Example:",[26,687,689],{"className":581,"code":688,"language":583,"meta":31,"style":31},"[Service]\nEnvironment=\"FLASK_ENV=production\"\nEnvironment=\"SECRET_KEY=replace-me\"\nEnvironmentFile=\u002Fetc\u002Fmyapp\u002Fmyapp.env\n",[33,690,691,695,700,705],{"__ignoreMap":31},[36,692,693],{"class":38,"line":39},[36,694,609],{},[36,696,697],{"class":38,"line":63},[36,698,699],{},"Environment=\"FLASK_ENV=production\"\n",[36,701,702],{"class":38,"line":85},[36,703,704],{},"Environment=\"SECRET_KEY=replace-me\"\n",[36,706,707],{"class":38,"line":98},[36,708,709],{},"EnvironmentFile=\u002Fetc\u002Fmyapp\u002Fmyapp.env\n",[215,711],{},"Then verify the file exists and is readable:",[26,714,716],{"className":28,"code":715,"language":30,"meta":31,"style":31},"ls -l \u002Fetc\u002Fmyapp\u002Fmyapp.env\n",[33,717,718],{"__ignoreMap":31},[36,719,720,722,724],{"class":38,"line":39},[36,721,380],{"class":42},[36,723,383],{"class":56},[36,725,726],{"class":46}," \u002Fetc\u002Fmyapp\u002Fmyapp.env\n",[208,728,729,732,217,734,767,769,770],{},[211,730,731],{},"Check directory and file permissions",[215,733],{},[26,735,737],{"className":28,"code":736,"language":30,"meta":31,"style":31},"namei -l \u002Fvar\u002Fwww\u002Fmyapp\nls -ld \u002Fvar\u002Fwww\u002Fmyapp\nls -la \u002Fvar\u002Fwww\u002Fmyapp\n",[33,738,739,749,758],{"__ignoreMap":31},[36,740,741,744,746],{"class":38,"line":39},[36,742,743],{"class":42},"namei",[36,745,383],{"class":56},[36,747,748],{"class":46}," \u002Fvar\u002Fwww\u002Fmyapp\n",[36,750,751,753,756],{"class":38,"line":63},[36,752,380],{"class":42},[36,754,755],{"class":56}," -ld",[36,757,748],{"class":46},[36,759,760,762,765],{"class":38,"line":85},[36,761,380],{"class":42},[36,763,764],{"class":56}," -la",[36,766,748],{"class":46},[215,768],{},"Confirm the service user can:",[241,771,772,775,778,781],{},[208,773,774],{},"traverse parent directories",[208,776,777],{},"read project files",[208,779,780],{},"access the virtualenv",[208,782,783],{},"create the socket file if using Unix sockets",[208,785,786,789,791,792,808,810,811,834,836,837,853,855,856],{},[211,787,788],{},"Validate port or Unix socket binding",[215,790],{},"For a TCP bind:",[26,793,795],{"className":28,"code":794,"language":30,"meta":31,"style":31},"\u002Fpath\u002Fto\u002Fvenv\u002Fbin\u002Fgunicorn --bind 127.0.0.1:8000 wsgi:app\n",[33,796,797],{"__ignoreMap":31},[36,798,799,802,804,806],{"class":38,"line":39},[36,800,801],{"class":42},"\u002Fpath\u002Fto\u002Fvenv\u002Fbin\u002Fgunicorn",[36,803,125],{"class":56},[36,805,128],{"class":46},[36,807,131],{"class":46},[215,809],{},"Check whether the port is already in use:",[26,812,814],{"className":28,"code":813,"language":30,"meta":31,"style":31},"ss -ltnp | grep 8000\n",[33,815,816],{"__ignoreMap":31},[36,817,818,821,824,828,831],{"class":38,"line":39},[36,819,820],{"class":42},"ss",[36,822,823],{"class":56}," -ltnp",[36,825,827],{"class":826},"szBVR"," |",[36,829,830],{"class":42}," grep",[36,832,833],{"class":56}," 8000\n",[215,835],{},"For a Unix socket bind:",[26,838,840],{"className":28,"code":839,"language":30,"meta":31,"style":31},"\u002Fpath\u002Fto\u002Fvenv\u002Fbin\u002Fgunicorn --bind unix:\u002Frun\u002Fgunicorn\u002Fmyapp.sock wsgi:app\n",[33,841,842],{"__ignoreMap":31},[36,843,844,846,848,851],{"class":38,"line":39},[36,845,801],{"class":42},[36,847,125],{"class":56},[36,849,850],{"class":46}," unix:\u002Frun\u002Fgunicorn\u002Fmyapp.sock",[36,852,131],{"class":46},[215,854],{},"Ensure the socket directory exists:",[26,857,859],{"className":28,"code":858,"language":30,"meta":31,"style":31},"sudo mkdir -p \u002Frun\u002Fgunicorn\nsudo chown www-data:www-data \u002Frun\u002Fgunicorn\n",[33,860,861,874],{"__ignoreMap":31},[36,862,863,865,868,871],{"class":38,"line":39},[36,864,43],{"class":42},[36,866,867],{"class":46}," mkdir",[36,869,870],{"class":56}," -p",[36,872,873],{"class":46}," \u002Frun\u002Fgunicorn\n",[36,875,876,878,881,884],{"class":38,"line":63},[36,877,43],{"class":42},[36,879,880],{"class":46}," chown",[36,882,883],{"class":46}," www-data:www-data",[36,885,873],{"class":46},[208,887,888,891,217,893,911,913],{},[211,889,890],{},"Verify the systemd unit syntax",[215,892],{},[26,894,896],{"className":28,"code":895,"language":30,"meta":31,"style":31},"sudo systemd-analyze verify \u002Fetc\u002Fsystemd\u002Fsystem\u002Fgunicorn.service\n",[33,897,898],{"__ignoreMap":31},[36,899,900,902,905,908],{"class":38,"line":39},[36,901,43],{"class":42},[36,903,904],{"class":46}," systemd-analyze",[36,906,907],{"class":46}," verify",[36,909,910],{"class":46}," \u002Fetc\u002Fsystemd\u002Fsystem\u002Fgunicorn.service\n",[215,912],{},"Fix any invalid directives or formatting errors.",[208,915,916,919,217,921],{},[211,917,918],{},"Reload systemd after changing the unit file",[215,920],{},[26,922,924],{"className":28,"code":923,"language":30,"meta":31,"style":31},"sudo systemctl daemon-reload\n",[33,925,926],{"__ignoreMap":31},[36,927,928,930,932],{"class":38,"line":39},[36,929,43],{"class":42},[36,931,47],{"class":46},[36,933,152],{"class":46},[208,935,936,939,217,941,970,972,973],{},[211,937,938],{},"Restart the service and verify it starts",[215,940],{},[26,942,944],{"className":28,"code":943,"language":30,"meta":31,"style":31},"sudo systemctl restart gunicorn\nsudo systemctl status gunicorn --no-pager -l\n",[33,945,946,956],{"__ignoreMap":31},[36,947,948,950,952,954],{"class":38,"line":39},[36,949,43],{"class":42},[36,951,47],{"class":46},[36,953,162],{"class":46},[36,955,95],{"class":46},[36,957,958,960,962,964,966,968],{"class":38,"line":63},[36,959,43],{"class":42},[36,961,47],{"class":46},[36,963,50],{"class":46},[36,965,53],{"class":46},[36,967,57],{"class":56},[36,969,60],{"class":56},[215,971],{},"Expected result:",[241,974,975],{},[208,976,977],{},[33,978,979],{},"active (running)",[208,981,982,985,987,988,1016,1018,1019],{},[211,983,984],{},"Confirm Gunicorn is listening",[215,986],{},"For TCP:",[26,989,991],{"className":28,"code":990,"language":30,"meta":31,"style":31},"ss -ltnp | grep 8000\ncurl -I http:\u002F\u002F127.0.0.1:8000\n",[33,992,993,1005],{"__ignoreMap":31},[36,994,995,997,999,1001,1003],{"class":38,"line":39},[36,996,820],{"class":42},[36,998,823],{"class":56},[36,1000,827],{"class":826},[36,1002,830],{"class":42},[36,1004,833],{"class":56},[36,1006,1007,1010,1013],{"class":38,"line":63},[36,1008,1009],{"class":42},"curl",[36,1011,1012],{"class":56}," -I",[36,1014,1015],{"class":46}," http:\u002F\u002F127.0.0.1:8000\n",[215,1017],{},"For Unix sockets:",[26,1020,1022],{"className":28,"code":1021,"language":30,"meta":31,"style":31},"ss -lx | grep gunicorn\n",[33,1023,1024],{"__ignoreMap":31},[36,1025,1026,1028,1031,1033,1035],{"class":38,"line":39},[36,1027,820],{"class":42},[36,1029,1030],{"class":56}," -lx",[36,1032,827],{"class":826},[36,1034,830],{"class":42},[36,1036,95],{"class":46},[208,1038,1039,1042,1044,1045,1060,1062,1063,682,1068,1070,1071,682],{},[211,1040,1041],{},"If Nginx is in front of Gunicorn, test the full stack",[215,1043],{},"First validate Nginx:",[26,1046,1048],{"className":28,"code":1047,"language":30,"meta":31,"style":31},"sudo nginx -t\n",[33,1049,1050],{"__ignoreMap":31},[36,1051,1052,1054,1057],{"class":38,"line":39},[36,1053,43],{"class":42},[36,1055,1056],{"class":46}," nginx",[36,1058,1059],{"class":56}," -t\n",[215,1061],{},"Then test upstream connectivity and request flow. If Nginx still cannot reach Gunicorn, continue with ",[1064,1065,1067],"a",{"href":1066},"\u002Ffix-issues\u002Ffix-nginx-not-connecting-to-gunicorn-connection-refused","Fix: Nginx Not Connecting to Gunicorn (Connection Refused)",[215,1069],{},"For a complete baseline setup, see ",[1064,1072,1074],{"href":1073},"\u002Fdeploy\u002Fdeploy-flask-with-nginx-plus-gunicorn-step-by-step-guide","Deploy Flask with Nginx + Gunicorn (Step-by-Step Guide)",[18,1076,1078],{"id":1077},"common-causes","Common Causes",[241,1080,1081,1093,1102,1115,1125,1136,1142,1148,1157,1163],{},[208,1082,1083,1089,1090,1092],{},[211,1084,1085,1086,1088],{},"Wrong ",[33,1087,182],{}," path"," → systemd cannot launch Gunicorn → point ",[33,1091,182],{}," to the correct virtualenv binary and reload systemd.",[208,1094,1095,1101],{},[211,1096,1097,1098],{},"Incorrect ",[33,1099,1100],{},"WorkingDirectory"," → Gunicorn cannot import the Flask app module → set the project root correctly in the unit file.",[208,1103,1104,1114],{},[211,1105,1106,1107,1110,1111],{},"Bad WSGI target such as ",[33,1108,1109],{},"app:app"," vs ",[33,1112,1113],{},"wsgi:app"," → Gunicorn starts but app import fails → use the correct module and object name.",[208,1116,1117,1120,1121,1124],{},[211,1118,1119],{},"Missing dependencies in the virtualenv"," → startup raises ",[33,1122,1123],{},"ModuleNotFoundError"," → install requirements in the same virtualenv used by the service.",[208,1126,1127,1130,1131,679,1133,1135],{},[211,1128,1129],{},"Environment variables not loaded"," → app crashes during import or config initialization → add ",[33,1132,353],{},[33,1134,358],{}," to the service.",[208,1137,1138,1141],{},[211,1139,1140],{},"Service user lacks permission to app files or socket path"," → Gunicorn cannot read code or create bind target → fix ownership and directory permissions.",[208,1143,1144,1147],{},[211,1145,1146],{},"Port already in use or socket path invalid"," → Gunicorn cannot bind → free the port, remove stale sockets, or fix the bind path.",[208,1149,1150,1156],{},[211,1151,1152,1153],{},"Unit file changed without ",[33,1154,1155],{},"systemctl daemon-reload"," → old configuration still used → reload systemd and restart the service.",[208,1158,1159,1162],{},[211,1160,1161],{},"Syntax errors or runtime errors in app startup code"," → Gunicorn exits immediately → test imports manually and review traceback in logs.",[208,1164,1165,1168],{},[211,1166,1167],{},"SELinux or restrictive server policy blocks file or socket access"," → service appears correctly configured but still fails → inspect security policy and file contexts where applicable.",[18,1170,1172],{"id":1171},"debugging-section","Debugging Section",[14,1174,1175],{},"Use these commands during diagnosis:",[26,1177,1179],{"className":28,"code":1178,"language":30,"meta":31,"style":31},"sudo systemctl status gunicorn --no-pager -l\nsudo journalctl -u gunicorn -n 200 --no-pager\nsudo journalctl -xe --no-pager\nsudo systemctl cat gunicorn\nsudo systemd-analyze verify \u002Fetc\u002Fsystemd\u002Fsystem\u002Fgunicorn.service\nls -l \u002Fpath\u002Fto\u002Fvenv\u002Fbin\u002Fgunicorn\ncd \u002Fpath\u002Fto\u002Fapp && source \u002Fpath\u002Fto\u002Fvenv\u002Fbin\u002Factivate && python -c \"from wsgi import app; print(app)\"\nsudo -u www-data bash -lc 'cd \u002Fpath\u002Fto\u002Fapp && \u002Fpath\u002Fto\u002Fvenv\u002Fbin\u002Fgunicorn --bind 127.0.0.1:8000 wsgi:app'\nnamei -l \u002Fpath\u002Fto\u002Fapp\nls -ld \u002Fpath\u002Fto\u002Fapp \u002Fpath\u002Fto\u002Fapp\u002F*\nss -ltnp | grep 8000\nss -lx | grep gunicorn\nsudo nginx -t\ncurl -I http:\u002F\u002F127.0.0.1:8000\n",[33,1180,1181,1195,1211,1222,1232,1242,1250,1271,1285,1293,1307,1319,1331,1339],{"__ignoreMap":31},[36,1182,1183,1185,1187,1189,1191,1193],{"class":38,"line":39},[36,1184,43],{"class":42},[36,1186,47],{"class":46},[36,1188,50],{"class":46},[36,1190,53],{"class":46},[36,1192,57],{"class":56},[36,1194,60],{"class":56},[36,1196,1197,1199,1201,1203,1205,1207,1209],{"class":38,"line":63},[36,1198,43],{"class":42},[36,1200,68],{"class":46},[36,1202,71],{"class":56},[36,1204,53],{"class":46},[36,1206,76],{"class":56},[36,1208,290],{"class":56},[36,1210,82],{"class":56},[36,1212,1213,1215,1217,1220],{"class":38,"line":85},[36,1214,43],{"class":42},[36,1216,68],{"class":46},[36,1218,1219],{"class":56}," -xe",[36,1221,82],{"class":56},[36,1223,1224,1226,1228,1230],{"class":38,"line":98},[36,1225,43],{"class":42},[36,1227,47],{"class":46},[36,1229,92],{"class":46},[36,1231,95],{"class":46},[36,1233,1234,1236,1238,1240],{"class":38,"line":105},[36,1235,43],{"class":42},[36,1237,904],{"class":46},[36,1239,907],{"class":46},[36,1241,910],{"class":46},[36,1243,1244,1246,1248],{"class":38,"line":112},[36,1245,380],{"class":42},[36,1247,383],{"class":56},[36,1249,386],{"class":46},[36,1251,1252,1254,1256,1258,1260,1263,1265,1267,1269],{"class":38,"line":134},[36,1253,443],{"class":56},[36,1255,446],{"class":46},[36,1257,450],{"class":449},[36,1259,391],{"class":56},[36,1261,1262],{"class":46}," \u002Fpath\u002Fto\u002Fvenv\u002Fbin\u002Factivate",[36,1264,450],{"class":449},[36,1266,500],{"class":42},[36,1268,503],{"class":56},[36,1270,506],{"class":46},[36,1272,1273,1275,1277,1279,1281,1283],{"class":38,"line":139},[36,1274,43],{"class":42},[36,1276,71],{"class":56},[36,1278,119],{"class":46},[36,1280,547],{"class":46},[36,1282,550],{"class":56},[36,1284,553],{"class":46},[36,1286,1287,1289,1291],{"class":38,"line":145},[36,1288,743],{"class":42},[36,1290,383],{"class":56},[36,1292,489],{"class":46},[36,1294,1295,1297,1299,1301,1304],{"class":38,"line":155},[36,1296,380],{"class":42},[36,1298,755],{"class":56},[36,1300,446],{"class":46},[36,1302,1303],{"class":46}," \u002Fpath\u002Fto\u002Fapp\u002F",[36,1305,1306],{"class":56},"*\n",[36,1308,1309,1311,1313,1315,1317],{"class":38,"line":167},[36,1310,820],{"class":42},[36,1312,823],{"class":56},[36,1314,827],{"class":826},[36,1316,830],{"class":42},[36,1318,833],{"class":56},[36,1320,1321,1323,1325,1327,1329],{"class":38,"line":642},[36,1322,820],{"class":42},[36,1324,1030],{"class":56},[36,1326,827],{"class":826},[36,1328,830],{"class":42},[36,1330,95],{"class":46},[36,1332,1333,1335,1337],{"class":38,"line":647},[36,1334,43],{"class":42},[36,1336,1056],{"class":46},[36,1338,1059],{"class":56},[36,1340,1341,1343,1345],{"class":38,"line":653},[36,1342,1009],{"class":42},[36,1344,1012],{"class":56},[36,1346,1015],{"class":46},[14,1348,1349],{},"What to look for:",[241,1351,1352,1360,1365,1377,1386,1389],{},[208,1353,1354,679,1356,1359],{},[33,1355,1123],{},[33,1357,1358],{},"ImportError"," → Flask app import problem",[208,1361,1362,1364],{},[33,1363,257],{}," → service user cannot access code, virtualenv, or socket directory",[208,1366,1367,1370,1371,1373,1374,1376],{},[33,1368,1369],{},"No such file or directory"," → bad path in ",[33,1372,182],{},", ",[33,1375,1100],{},", or environment file",[208,1378,1379,679,1382,1385],{},[33,1380,1381],{},"Failed at step EXEC",[33,1383,1384],{},"203\u002FEXEC"," → invalid executable path or non-executable binary",[208,1387,1388],{},"address already in use errors → port or socket conflict",[208,1390,1391],{},"service works manually but not in systemd → unit file environment, user, or working directory mismatch",[14,1393,1394,1395,682],{},"If the Gunicorn process becomes active but requests still fail, check Nginx upstream configuration and reverse proxy behavior in ",[1064,1396,1067],{"href":1066},[18,1398,1400],{"id":1399},"checklist","Checklist",[241,1402,1405,1421,1429,1437,1443,1449,1455,1461,1470,1479],{"className":1403},[1404],"contains-task-list",[208,1406,1409,1413,1414,1417,1418,1420],{"className":1407},[1408],"task-list-item",[1410,1411],"input",{"disabled":101,"type":1412},"checkbox"," ",[33,1415,1416],{},"gunicorn"," binary path in ",[33,1419,182],{}," exists and is executable.",[208,1422,1424,1413,1426,1428],{"className":1423},[1408],[1410,1425],{"disabled":101,"type":1412},[33,1427,1100],{}," points to the Flask project root.",[208,1430,1432,1434,1435,682],{"className":1431},[1408],[1410,1433],{"disabled":101,"type":1412}," WSGI module reference is correct, such as ",[33,1436,1113],{},[208,1438,1440,1442],{"className":1439},[1408],[1410,1441],{"disabled":101,"type":1412}," The virtualenv contains Gunicorn and Flask dependencies.",[208,1444,1446,1448],{"className":1445},[1408],[1410,1447],{"disabled":101,"type":1412}," The systemd service user can read the app files and enter all parent directories.",[208,1450,1452,1454],{"className":1451},[1408],[1410,1453],{"disabled":101,"type":1412}," Required environment variables are available to the service.",[208,1456,1458,1460],{"className":1457},[1408],[1410,1459],{"disabled":101,"type":1412}," The configured port or Unix socket can be created and is not already in use.",[208,1462,1464,1413,1466,1469],{"className":1463},[1408],[1410,1465],{"disabled":101,"type":1412},[33,1467,1468],{},"sudo systemctl daemon-reload"," was run after editing the unit file.",[208,1471,1473,1413,1475,1478],{"className":1472},[1408],[1410,1474],{"disabled":101,"type":1412},[33,1476,1477],{},"sudo systemctl restart gunicorn"," completes successfully.",[208,1480,1482,1413,1484,1487,1488,682],{"className":1481},[1408],[1410,1483],{"disabled":101,"type":1412},[33,1485,1486],{},"systemctl status gunicorn"," shows ",[33,1489,979],{},[14,1491,1492,1493,682],{},"For final production verification, use ",[1064,1494,1496],{"href":1495},"\u002Fchecklist\u002Fflask-production-checklist-everything-you-must-do","Flask Production Checklist (Everything You Must Do)",[18,1498,1500],{"id":1499},"related-guides","Related Guides",[241,1502,1503,1507,1511],{},[208,1504,1505],{},[1064,1506,1074],{"href":1073},[208,1508,1509],{},[1064,1510,1067],{"href":1066},[208,1512,1513],{},[1064,1514,1496],{"href":1495},[18,1516,1518],{"id":1517},"faq","FAQ",[14,1520,1521,1524,1526,1527,1529,1530,1533],{},[211,1522,1523],{},"Q: What is the fastest way to identify why the Gunicorn service failed?",[215,1525],{},"\nA: Check ",[33,1528,1486],{}," first, then read ",[33,1531,1532],{},"journalctl -u gunicorn"," for the exact startup error or traceback.",[14,1535,1536,1539,1541],{},[211,1537,1538],{},"Q: Why does systemd report the service failed immediately after start?",[215,1540],{},"\nA: Gunicorn usually exited during app import, failed to execute the configured binary, or could not bind the configured port or socket.",[14,1543,1544,1547,1549,1550,1552],{},[211,1545,1546],{},"Q: Can a wrong virtualenv cause the service to fail?",[215,1548],{},"\nA: Yes. If ",[33,1551,182],{}," points to the wrong environment, Gunicorn or Flask dependencies may be missing.",[14,1554,1555,1558,1560],{},[211,1556,1557],{},"Q: Do I need to run Gunicorn as the same user configured in systemd?",[215,1559],{},"\nA: Yes. Manual tests should use the same service user to reproduce permission and environment issues accurately.",[14,1562,1563,1566,1568,1569,1572],{},[211,1564,1565],{},"Q: Should I debug with a TCP bind before using a Unix socket?",[215,1567],{},"\nA: Yes. Binding to ",[33,1570,1571],{},"127.0.0.1:8000"," is often easier to validate during troubleshooting.",[14,1574,1575,1582,1584,1585,1587],{},[211,1576,1577,1578,1581],{},"Q: What does ",[33,1579,1580],{},"code=exited, status=203\u002FEXEC"," mean?",[215,1583],{},"\nA: systemd could not execute the command in ",[33,1586,182],{},", usually because the path is wrong or not executable.",[14,1589,1590,1593,1595,1596,1599],{},[211,1591,1592],{},"Q: Why does Gunicorn work manually but fail as a service?",[215,1594],{},"\nA: The service is likely using a different user, working directory, ",[33,1597,1598],{},"PATH",", or environment variable set.",[14,1601,1602,1609,1611],{},[211,1603,1604,1605,1608],{},"Q: Do I need ",[33,1606,1607],{},"daemon-reload"," after changing the unit file?",[215,1610],{},"\nA: Yes. systemd does not apply unit file changes until you reload its configuration.",[18,1613,1615],{"id":1614},"final-takeaway","Final Takeaway",[14,1617,1618],{},"A failed Gunicorn service is usually caused by a systemd configuration error, an app import failure, or a permission problem. Verify the unit file, test the app manually as the service user, and confirm the bind target and environment before restarting the service.",[1620,1621,1622],"style",{},"html pre.shiki code .sScJk, html code.shiki .sScJk{--shiki-default:#6F42C1;--shiki-dark:#B392F0}html pre.shiki code .sZZnC, html code.shiki .sZZnC{--shiki-default:#032F62;--shiki-dark:#9ECBFF}html pre.shiki code .sj4cs, html code.shiki .sj4cs{--shiki-default:#005CC5;--shiki-dark:#79B8FF}html pre.shiki code .sJ8bj, html code.shiki .sJ8bj{--shiki-default:#6A737D;--shiki-dark:#6A737D}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html pre.shiki code .sVt8B, html code.shiki .sVt8B{--shiki-default:#24292E;--shiki-dark:#E1E4E8}html pre.shiki code .szBVR, html code.shiki .szBVR{--shiki-default:#D73A49;--shiki-dark:#F97583}",{"title":31,"searchDepth":63,"depth":63,"links":1624},[1625,1626,1627,1628,1629,1630,1631,1632,1633],{"id":20,"depth":63,"text":21},{"id":186,"depth":63,"text":187},{"id":202,"depth":63,"text":203},{"id":1077,"depth":63,"text":1078},{"id":1171,"depth":63,"text":1172},{"id":1399,"depth":63,"text":1400},{"id":1499,"depth":63,"text":1500},{"id":1517,"depth":63,"text":1518},{"id":1614,"depth":63,"text":1615},"Complete guide on flask gunicorn service failed to start for Flask production environments.","md",{"ogTitle":5,"ogDescription":1634,"twitterCard":1637,"robots":1638,"canonical":1639},"summary_large_image","index, follow","https:\u002F\u002Fflask-deployment.com\u002Ffix-issues\u002Fflask-gunicorn-service-failed-to-start","\u002Ffix-issues\u002Fflask-gunicorn-service-failed-to-start",{"title":5,"description":1634},"fix-issues\u002Fflask-gunicorn-service-failed-to-start","zCbVXzajGWEELXabKgYXdphAWSvH08Vpda3nJgKeRlw",1776805765714]