https://sweetcode.com/assets/js/c61dc4b3.2e99a56d.js

1"use strict";(globalThis.webpackChunkdocusaurus_test=globalThis.webpackChunkdocusaurus_test||[]).push([[5567],{31090(e,n,t){t.r(n),t.d(n,{assets:()=>a,contentTitle:()=>r,default:()=>c,frontMatter:()=>l,metadata:()=>o,toc:()=>d});let o=JSON.parse('{"id":"plugin-installation-problems","title":"Plugin Installation Problems","description":"This page covers what to do when the plugin ZIP downloads fine, but WordPress cannot install it. It applies to all SweetCode plugins, including Pixel Manager for WooCommerce, Google Automated Discounts for WooCommerce, and Google Customer Reviews for WooCommerce.","source":"@site/docs/plugin-installation-problems.md","sourceDirName":".","slug":"/plugin-installation-problems","permalink":"/docs/plugin-installation-problems","draft":false,"unlisted":false,"tags":[],"version":"current","lastUpdatedAt":1789878036000,"frontMatter":{}}');var s=t(74848),i=t(28453);let l={},r="Plugin Installation Problems",a={},d=[{value:"Symptoms",id:"symptoms",level:2},{value:"Step 1: Rule out the ZIP and the plugin",id:"step-1-rule-out-the-zip-and-the-plugin",level:2},{value:"Step 2: Install the plugin via SFTP or FTP",id:"step-2-install-the-plugin-via-sftp-or-ftp",level:2},{value:"Step 3: Have your hosting support fix the cause",id:"step-3-have-your-hosting-support-fix-the-cause",level:2},{value:"Step 4: If it still does not work",id:"step-4-if-it-still-does-not-work",level:2},{value:"Related pages",id:"related-pages",level:2}];function h(e){let n={a:"a",admonition:"admonition",blockquote:"blockquote",code:"code",h1:"h1",h2:"h2",header:"header",li:"li",ol:"ol",p:"p",strong:"strong",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",ul:"ul",...(0,i.R)(),...e.components};return(0,s.jsxs)(s.Fragment,{children:[(0,s.jsx)(n.header,{children:(0,s.jsx)(n.h1,{id:"plugin-installation-problems",children:"Plugin Installation Problems"})}),"\n",(0,s.jsxs)(n.p,{children:["This page covers what to do when the plugin ZIP downloads fine, but WordPress cannot install it. It applies to all SweetCode plugins, including ",(0,s.jsx)(n.a,{href:"/plugins/pmw/",children:"Pixel Manager for WooCommerce"}),", ",(0,s.jsx)(n.a,{href:"/plugins/gadwc/",children:"Google Automated Discounts for WooCommerce"}),", and ",(0,s.jsx)(n.a,{href:"/plugins/gcr/",children:"Google Customer Reviews for WooCommerce"}),"."]}),"\n",(0,s.jsx)(n.p,{children:"In almost every case we have seen, this is not a problem with the plugin ZIP. It is the server or a firewall in front of it that refuses the upload."}),"\n",(0,s.jsx)(n.h2,{id:"symptoms",children:"Symptoms"}),"\n",(0,s.jsx)(n.p,{children:"Any of these point to a blocked or aborted upload:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.strong,{children:"Plugins \u2192 Add New \u2192 Upload Plugin"})," spins forever and nothing happens"]}),"\n",(0,s.jsx)(n.li,{children:"The upload ends in a blank page, a white screen, or an HTTP 500 error"}),"\n",(0,s.jsxs)(n.li,{children:["You see ",(0,s.jsx)(n.code,{children:"Installation failed"}),", ",(0,s.jsx)(n.code,{children:"The link you followed has expired"}),", or ",(0,s.jsx)(n.code,{children:"HTTP error"})]}),"\n",(0,s.jsx)(n.li,{children:"You see a 403 Forbidden, a 413 error, or the connection is reset mid-upload"}),"\n",(0,s.jsx)(n.li,{children:"WordPress asks you for FTP credentials to complete the installation"}),"\n"]}),"\n",(0,s.jsx)(n.h2,{id:"step-1-rule-out-the-zip-and-the-plugin",children:"Step 1: Rule out the ZIP and the plugin"}),"\n",(0,s.jsxs)(n.ol,{children:["\n",(0,s.jsxs)(n.li,{children:["Re-download the ZIP from your ",(0,s.jsx)(n.a,{href:"https://sweetcode.com/freemius-account/",children:"customer account"}),". An interrupted download leaves a truncated archive that no server can install."]}),"\n",(0,s.jsx)(n.li,{children:"Open the ZIP locally. It should contain exactly one plugin folder. If your browser or macOS unpacked it automatically, re-zipping the folder yourself often produces a nested structure WordPress rejects, so always upload the original file."}),"\n",(0,s.jsxs)(n.li,{children:["Try uploading a different plugin ZIP of a similar size, for example any plugin downloaded from wordpress.org. ",(0,s.jsx)(n.strong,{children:"If that upload fails too, the problem is your server, not our plugin"}),", and the rest of this page applies."]}),"\n"]}),"\n",(0,s.jsx)(n.h2,{id:"step-2-install-the-plugin-via-sftp-or-ftp",children:"Step 2: Install the plugin via SFTP or FTP"}),"\n",(0,s.jsx)(n.p,{children:"This is the fastest way to get the plugin running. It bypasses the WordPress uploader completely, and with it every server rule that blocks the upload."}),"\n",(0,s.jsxs)(n.ol,{children:["\n",(0,s.jsxs)(n.li,{children:["Unzip the plugin ZIP on your computer. You get a single folder named after the plugin, for example ",(0,s.jsx)(n.code,{children:"woocommerce-google-adwords-conversion-tracking-tag"})," for the Pixel Manager."]}),"\n",(0,s.jsx)(n.li,{children:"Connect to your server with an SFTP or FTP client, or open the file manager in your hosting control panel."}),"\n",(0,s.jsxs)(n.li,{children:["If you are replacing an older version of the same plugin, deactivate it in WordPress first, then rename its existing folder in ",(0,s.jsx)(n.code,{children:"wp-content/plugins/"})," by appending ",(0,s.jsx)(n.code,{children:"-old"})," to the folder name. Rename it rather than deleting it through the WordPress ",(0,s.jsx)(n.strong,{children:"Delete"})," button, because the WordPress delete runs the plugin's uninstall routine and can drop its settings."]}),"\n",(0,s.jsxs)(n.li,{children:["Upload the unzipped folder into ",(0,s.jsx)(n.code,{children:"wp-content/plugins/"}),"."]}),"\n",(0,s.jsxs)(n.li,{children:["Go to ",(0,s.jsx)(n.strong,{children:"Plugins"})," in WordPress. The plugin now appears in the list. Activate it and enter your license key."]}),"\n",(0,s.jsx)(n.li,{children:"Once everything works, remove the renamed old folder."}),"\n"]}),"\n",(0,s.jsx)(n.p,{children:"Your settings and your license are stored in the database, not in the plugin folder, so a manual installation keeps both."}),"\n",(0,s.jsx)(n.admonition,{title:"Do you have SSH access?",type:"tip",children:(0,s.jsxs)(n.p,{children:["Then a single command does the same thing: ",(0,s.jsx)(n.code,{children:"wp plugin install /path/to/plugin.zip --activate"})]})}),"\n",(0,s.jsxs)(n.p,{children:["If you prefer to skip the ZIP altogether, our plugins can also be installed with Composer. See ",(0,s.jsx)(n.a,{href:"/docs/license-management#install-plugins-with-composer",children:"Install Plugins with Composer"}),"."]}),"\n",(0,s.jsx)(n.h2,{id:"step-3-have-your-hosting-support-fix-the-cause",children:"Step 3: Have your hosting support fix the cause"}),"\n",(0,s.jsx)(n.p,{children:"The manual installation is a workaround. Your site will hit the same wall on the next plugin upload or update, so it is worth getting the underlying server configuration fixed. These are the usual causes:"}),"\n",(0,s.jsxs)(n.table,{children:[(0,s.jsx)(n.thead,{children:(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.th,{children:"Cause"}),(0,s.jsx)(n.th,{children:"What you typically see"})]})}),(0,s.jsxs)(n.tbody,{children:[(0,s.jsxs)(n.tr,{children:[(0,s.jsxs)(n.td,{children:[(0,s.jsx)(n.code,{children:"upload_max_filesize"})," or ",(0,s.jsx)(n.code,{children:"post_max_size"})," set too low"]}),(0,s.jsx)(n.td,{children:"The uploader rejects the file immediately, or the error mentions the file exceeding a limit"})]}),(0,s.jsxs)(n.tr,{children:[(0,s.jsxs)(n.td,{children:[(0,s.jsx)(n.code,{children:"max_execution_time"})," or ",(0,s.jsx)(n.code,{children:"memory_limit"})," too low"]}),(0,s.jsx)(n.td,{children:"A long spinner, then a blank page or an HTTP 500"})]}),(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.td,{children:"A mod_security or WAF rule on the plugin upload endpoint"}),(0,s.jsx)(n.td,{children:'A 403 Forbidden, a generic "blocked" page, or a reset connection'})]}),(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.td,{children:"A request size limit in a reverse proxy or CDN in front of the site"}),(0,s.jsx)(n.td,{children:"A 413 error, often after the upload appears to complete"})]}),(0,s.jsxs)(n.tr,{children:[(0,s.jsxs)(n.td,{children:["Wrong ownership or permissions on ",(0,s.jsx)(n.code,{children:"wp-content/plugins/"}),", or a read-only filesystem"]}),(0,s.jsx)(n.td,{children:"WordPress asks for FTP credentials, or reports that it could not create a directory"})]}),(0,s.jsxs)(n.tr,{children:[(0,s.jsx)(n.td,{children:"A full disk or a filled hosting quota"}),(0,s.jsx)(n.td,{children:"Errors about not being able to copy or write files"})]})]})]}),"\n",(0,s.jsx)(n.p,{children:"Only your host can look into most of these, so open a ticket with them and give them something concrete to work with:"}),"\n",(0,s.jsxs)(n.blockquote,{children:["\n",(0,s.jsxs)(n.p,{children:["Uploading a plugin ZIP through the WordPress admin (",(0,s.jsx)(n.code,{children:"/wp-admin/update.php?action=upload-plugin"}

1),") fails on my site. Please check the mod_security/WAF log and the PHP error log for the attempt at [date and time, including your time zone], and let me know which rule or limit blocked it. Please also confirm the effective values of ",(0,s.jsx)(n.code,{children:"upload_max_filesize"}),", ",(0,s.jsx)(n.code,{children:"post_max_size"}),", ",(0,s.jsx)(n.code,{children:"max_execution_time"}),", and ",(0,s.jsx)(n.code,{children:"memory_limit"})," for the site, and raise them if they are below the WordPress recommendations."]}),"\n"]}),"\n",(0,s.jsx)(n.p,{children:"Note that our plugin ZIPs are not unusually large. If a small ZIP fails to upload, a firewall rule or a timeout is a far more likely cause than a size limit, so ask your host to check the firewall logs specifically, not just the PHP limits."}),"\n",(0,s.jsx)(n.h2,{id:"step-4-if-it-still-does-not-work",children:"Step 4: If it still does not work"}),"\n",(0,s.jsxs)(n.p,{children:["Contact us through ",(0,s.jsx)(n.a,{href:"/support/",children:"support"})," or at ",(0,s.jsx)(n.a,{href:"mailto:[email protected]",children:"[email protected]"}),", and include:"]}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:"Which plugin and which version you are trying to install"}),"\n",(0,s.jsx)(n.li,{children:"Your hosting provider, and whether the site sits behind a CDN or a security service"}),"\n",(0,s.jsx)(n.li,{children:"The exact error message or a screenshot of what you see"}),"\n",(0,s.jsx)(n.li,{children:"Whether a plugin ZIP from wordpress.org fails in the same way"}),"\n",(0,s.jsxs)(n.li,{children:["Your WordPress, WooCommerce, and PHP versions, from ",(0,s.jsx)(n.strong,{children:"Tools \u2192 Site Health \u2192 Info"})]}),"\n"]}),"\n",(0,s.jsx)(n.h2,{id:"related-pages",children:"Related pages"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.a,{href:"/docs/license-management",children:"License Management"})," for downloads, license keys, and installing the pro version"]}),"\n",(0,s.jsx)(n.li,{children:(0,s.jsx)(n.a,{href:"/docs/pmw/setup/plugin-installation",children:"Pixel Manager installation"})}),"\n",(0,s.jsx)(n.li,{children:(0,s.jsx)(n.a,{href:"/docs/gadwc/setup",children:"Google Automated Discounts setup"})}),"\n",(0,s.jsx)(n.li,{children:(0,s.jsx)(n.a,{href:"/docs/gcr/setup",children:"Google Customer Reviews setup"})}),"\n"]})]})}function c(e={}){let{wrapper:n}={...(0,i.R)(),...e.components};return n?(0,s.jsx)(n,{...e,children:(0,s.jsx)(h,{...e})}):h(e)}}}]);